Server-side ingest

Send conversions from your backend when the source of truth isn't the browser — webhooks, subscriptions, invoicing, offline sales. All attribution, experiments, and dedup still work.

01Server-side ingest API

One endpoint, one JSON body. Authentication via project ID in the payload.

curl "https://api.sumidata.io/sdk/ingest" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"projectId":"proj_…","deviceId":"00000000-0000-0000-0000-000000000000","externalUserId":"user_7e2a9c","source":"backend","events":[{"name":"purchase","orderId":"ord_01HW","totalAmount":99.99,"currency":"USD"}]}'

import axios from 'axios'

await axios.post('https://api.sumidata.io/sdk/ingest', {
  projectId: process.env.SUMIDATA_PROJECT_ID,
  deviceId: user.sumidataDeviceId ?? '00000000-0000-0000-0000-000000000000',
  sessionId: user.sumidataSessionId,
  externalUserId: user.id,
  source: 'backend',
  events: [{
    name: 'purchase',
    orderId: order.id,
    totalAmount: order.total,
    currency: 'USD',
    timestamp: Date.now(),
  }]
})

{ "status": "ok" }

02The source field

Tell Sumidata where the event came from so reports can filter by origin.

Every envelope carries a source. Any string is accepted, but reports and the Partner API filter by the three canonical values below — stick to them unless you have a dedicated reason to branch.

03External user IDs

externalUserId is the cross-device anchor — pick a stable ID and never change it.

Server-side conversions don't have cookies or a device ID. Attribution hinges on externalUserId — the same identifier you pass to the browser SDK's identify() call. Pick one that won't change: your internal user UUID, the account ID, or a hashed email.

// Browser — at login
Sumidata.push('identify', [user.id])

// Server — at conversion. Same ID.
await ingest({ externalUserId: user.id, … })

• Normalize before sending — trim, lowercase email, checksum-case wallet addresses.
• Don't send a volatile ID (session cookies, generated tokens) — it breaks the user's journey.
• If you change the ID later, old events won't stitch to the new identity.

04Linking browser session to server

Carry the browser session into your server so conversions inherit UTM attribution.

Server-side conversions lose UTM attribution by default — there's no URL in your webhook handler. Fix this in three steps:

// Client — runs once the user is authenticated
const sumidataSessionId = window.Sumidata?.getSessionId?.()
const sumidataDeviceId = localStorage.getItem('sumidata_device_id')

await fetch('/api/users/me/analytics-ids', {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ sumidataSessionId, sumidataDeviceId })
})

// Server — save the IDs for later
user.sumidataSessionId = req.body.sumidataSessionId
user.sumidataDeviceId  = req.body.sumidataDeviceId
await users.save(user)

await ingest({
  externalUserId: user.id,
  deviceId: user.sumidataDeviceId,
  sessionId: user.sumidataSessionId,
  source: 'realtime',
  events: [{ name: 'purchase', … }]
})

05Full purchase payload reference

The full event schema. Only name, orderId, and totalAmount are strictly required for a purchase.

Identifiers

Pricing

Lifecycle

Attribution (optional — auto-resolved for conversions)

Event metadata (AAARRR funnel tagging)

Free-form

{
  "name": "purchase",
  "orderId": "ord_01HW…",
  "productId": "plan_pro_monthly",
  "productName": "Pro (monthly)",
  "productCategory": "subscription",
  "quantity": 1,
  "unitPrice": 99.00,
  "totalAmount": 79.00,
  "currency": "USD",
  "discountAmount": 20.00,
  "couponCode": "LAUNCH20",
  "isPrimarySale": true,
  "timestamp": 1713609164000,
  "_category": "revenue",
  "_feature": "checkout",
  "_surface": "app",
  "payload": { "billingProvider": "stripe" }
}

06Primary vs secondary sales

Flag first-ever purchases separately from repeat revenue — essential for LTV and cohort analysis.

isPrimarySale marks whether this is the customer's first-ever purchase. It drives new-vs-returning revenue splits, first-purchase LTV cohorts, and acquisition CAC math. Compute it against your database before firing.

-- Returns true if the user has no earlier purchases
SELECT NOT EXISTS (
  SELECT 1 FROM orders
  WHERE user_id = $1 AND status = 'paid' AND id <> $2
) AS is_primary_sale

const isPrimarySale = await orders.hasNoPriorPaidOrders(user.id, order.id)

await ingest({
  externalUserId: user.id,
  source: 'realtime',
  events: [{
    name: 'purchase',
    orderId: order.id,
    totalAmount: order.total,
    isPrimarySale,
  }]
})

07UTM attribution — auto-resolution

Conversions without explicit UTM fields inherit them from stored attribution history — no manual wiring needed.

For any event that looks like a conversion (has an orderId), Sumidata auto-fills missing UTM fields from its attribution tables. Resolution order:

1. Event payload — if utmSource etc. are set on the event, they win.
2. User attribution — latest entry in user_attribution for this externalUserId. This is populated from every browser session the user has ever had on any device.
3. Device attribution — latest entry in device_attribution for this deviceId. Used when there's no linked user yet.

Manual override — for edge cases

If the user never had a web session (API-only signup, mobile-only flow), stash the acquisition context at registration and attach it manually at conversion time:

// At signup — persist the acquisition context
const urlParams = Object.fromEntries(new URL(req.headers.referer).searchParams)
await users.create({ …userData, urlParams })

// At conversion — copy the stored UTMs onto the event
const event: SumidataEvent = {
  name: 'purchase', orderId: order.id, totalAmount: order.total,
  utmSource: user.urlParams?.utm_source,
  utmMedium: user.urlParams?.utm_medium,
  utmCampaign: user.urlParams?.utm_campaign,
}

await ingest({ externalUserId: user.id, source: 'realtime', events: [event] })

Multi-touch history

The user_attribution table stores every touchpoint, not just the latest. When you call the identify endpoint (/sdk/link-session-to-customer), Sumidata copies every prior device_attribution row onto the user — so you get full first-touch / last-touch / N-touch attribution out of the box. Query the table directly for custom journey analysis.

08A/B experiments

Register variant assignments once per session — sticky, idempotent, joined to every conversion automatically.

Experiments are a first-class Sumidata entity, not a tag on an event. Assignments live in a dedicated table (session_experiments) and get joined into every downstream analysis — revenue by variant, funnel-step by variant, replay filtering by variant. For the full integration guide (GrowthBook / Statsig / LaunchDarkly / Optimizely recipes, query patterns, limitations), see Experiments.

curl "https://api.sumidata.io/sdk/session-experiments" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"projectId":"…","deviceId":"…","sessionId":"…","experiments":[{"id":"pricing-v3","variant":"control"}]}'

{ "status": "ok" }     // new assignments inserted
{ "status": "skip" }   // all (session, experimentId) pairs already registered — no-op

Browser — via the SDK

The SDK has a first-class helper that takes the same shape and handles device/session IDs automatically:

Sumidata.push('identifyExperiment', [[
  { id: 'pricing-v3', variant: 'control' },
  { id: 'onboarding-flow', variant: 'short' },
]])

Server — when the session is on your backend

Useful when assignments are resolved server-side (feature-flag service, SSR rollout) and you already have the user's sessionId linked (see section 04). Call the endpoint directly:

await axios.post('https://api.sumidata.io/sdk/session-experiments', {
  projectId: process.env.SUMIDATA_PROJECT_ID,
  deviceId: user.sumidataDeviceId,
  sessionId: user.sumidataSessionId,
  experiments: flagService.getAssignments(user.id),
})

Sticky assignments (first-wins)

Sumidata deduplicates on (sessionId, experimentId). The first assignment for a pair is persisted forever — a later call with a different variant for the same experiment in the same session is a no-op (response: { status: "skip" }). This protects analysis from:

• Flicker-reassignment when a flag evaluator returns different values on re-mount.
• Double-fires when your SDK reloads the experiment list on route change.
• Race conditions between client assignment and server assignment.

Joining experiments to conversions

No special field is needed on the purchase event. The join happens on sessionId at query time:

SELECT
  se.variant,
  count(DISTINCT e.orderId) AS conversions,
  sum(e.totalAmount)               AS revenue
FROM events e
JOIN session_experiments se ON se.sessionId = e.sessionId
WHERE se.experimentId = 'pricing-v3'
  AND e.orderId != ''
GROUP BY se.variant

The AI Analyst does this join automatically — ask it "revenue by variant for pricing-v3 last 14 days".

09Coupons & discounts

Coupon + discount are separate fields, so reports can break down gross / discount / net without guessing.

Three fields work together to make promo campaigns measurable:

await ingest({
  externalUserId: user.id,
  source: 'realtime',
  events: [{
    name: 'purchase',
    orderId: order.id,
    productId: order.productId,
    quantity: 1,
    unitPrice: 99.00,      // gross per unit
    discountAmount: 20.00, // LAUNCH20 = 20% off
    totalAmount: 79.00,    // net, what you charged
    currency: 'USD',
    couponCode: 'LAUNCH20',
  }]
})

Common questions answered by the three fieldsCoupon field FAQ

• Which code lifted net revenue? — group by couponCode, sum totalAmount.
• Which code cannibalized margin? — group by couponCode, sum discountAmount.
• Gross sale value per code — totalAmount + discountAmount.
• Effective discount rate per campaign — discountAmount / (totalAmount + discountAmount).

10Error handling & retries

Conversions are revenue — never let one bad event drop the rest of the batch.

Ingest is idempotent by (orderId, productId), so retrying is always safe — a duplicate returns 400 and no event is written. Handle errors per-event, not per-batch:

async function sendConversion(event: SumidataEvent) {
  try {
    const res = await axios.post(URL, { projectId, externalUserId, source: 'realtime', events: [event] })
    return { ok: true }
  } catch (err: any) {
    const status = err.response?.status
    if (status >= 500 || status === 429) {
      await retryQueue.push(event)
    } else {
      logger.warn('Sumidata rejected event', { orderId: event.orderId, status })
    }
    return { ok: false, status }
  }
}

• 4xx (validation, including duplicate) — don't retry; log and skip.
• 5xx — requeue with exponential backoff.
• Network failure — requeue. Ingest will dedup on retry.
• Dead-letter queue — after N retries, park the event for manual inspection rather than blocking the pipeline.

11Configuration

Two environment variables. No client keys, no dashboards.

SUMIDATA_PROJECT_ID=proj_…
SUMIDATA_API_URL=https://api.sumidata.io/sdk/ingest

• SUMIDATA_PROJECT_ID — required. Without it, wrap the ingest call in a no-op and log a warning at boot rather than failing requests.
• SUMIDATA_API_URL — optional. Override for staging / proxy / on-premise ingest.

12The /sdk/* endpoint family

Six endpoints cover the full server-integration surface. Everything takes projectId in the body.

Conversions via /sdk/ingest are the most common use, but the SDK API exposes a small family of endpoints for the full lifecycle — sessions, identity, experiments. All live under the same host and take projectId in the JSON body.

13AI-agent quick reference

Drop this spec into an agent prompt to give it the full server-ingest surface.

base_url: https://api.sumidata.io
auth: projectId (UUID) in JSON body — no Bearer token, no api key header
content_type: application/json

primary_endpoint:
  path: POST /sdk/ingest
  idempotency: dedup key = (orderId, productId); duplicates reject whole batch with 400
  body:
    projectId: UUID, required
    deviceId: UUID, required (zero-UUID ok when no browser session)
    sessionId: UUID, optional for backend sources
    externalUserId: string, optional (stable user ID)
    source: 'realtime' | 'import' | 'backend' (any string accepted, but reports filter on these)
    events: Event[] — keep under 100 per batch
  response: { status: "ok" }

event_fields:
  required: [name]
  conversion_required: [orderId, totalAmount] (+ currency, recommended)
  pricing: [totalAmount, currency, quantity, unitPrice, discountAmount, couponCode]
  product: [productId, productName, productCategory]
  lifecycle: [isPrimarySale, timestamp (ms since epoch)]
  attribution: [utmSource, utmMedium, utmCampaign, utmTerm, utmContent] — auto-resolved from device/user attribution if omitted
  funnel_metadata: [_category, _feature, _surface] — see validation below
  payload: object — any free-form JSON; queryable via JSONExtract at query time

validation:
  _category: awareness | acquisition | activation | revenue | retention | referral
  _surface: marketing_site | app | mobile_app | docs
  _feature: regex ^[a-z0-9_]+$
  error_shape: { "errors": { "events[i].<field>": ["<message>"] } }

related_endpoints:
  - POST /sdk/link-session-to-customer — bind sessionId ↔ externalUserId
  - POST /sdk/session-experiments   — register A/B variants
  - POST /sdk/sessions/import       — import a historical session with caller-supplied UUID
  - GET  /api/partner/events        — read back ingested events (Bearer token)