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. Browser checkouts use Sumidata.purchase() instead - see Conversions.

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":"YOUR_PROJECT_ID","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.

Set a source on every envelope - when it is omitted the request is treated as sdk. Any string is accepted and stored on each event: the dashboard's Events filter offers backend and import, and the Partner API filters on any value. Stick to the three canonical values below 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 have no URL to read UTMs from. When the browser SDK has identified the user, a conversion with that externalUserId already inherits their latest campaign touch (section 07). To also cover visitors who were never identified, carry the browser IDs to your server 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. An orderId is what makes an event a purchase - send name and totalAmount with it.

Identifiers

Items

Pricing

Lifecycle

Attribution (optional - auto-resolved for conversions)

Event metadata (AAARRR funnel tagging)

Free-form

{
  "name": "purchase",
  "orderId": "ord_01HW…",
  "totalAmount": 79.00,
  "currency": "USD",
  "discountAmount": 20.00,
  "couponCode": "LAUNCH20",
  "isPrimarySale": true,
  "timestamp": 1713609164000,
  "items": [{
    "productId": "plan_pro_monthly",
    "productName": "Pro (monthly)",
    "productCategory": "subscription",
    "quantity": 1,
    "unitPrice": 99.00
  }],
  "_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 the Primary / Secondary Sales split (new-vs-returning revenue) in the Sales Report, and is what you need for first-purchase LTV cohorts and acquisition CAC math in your own queries. 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. It is filled each time the user is identified on a device, from that device's campaign history.
3. Device attribution - latest entry in device_attribution for this deviceId. Used when the event has no externalUserId or the user has no attribution entry 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, events 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
{ "status": "quota_exceeded" }   // monthly session quota used up - nothing registered

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 the one that sticks - 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.
• A client-side and a server-side assignment for the same session that arrive one after the other - two requests that arrive at the same moment can both be stored.

Joining experiments to conversions

No special field is needed on the purchase event. In your own queries the join happens on sessionId at query time (the Experiments dashboard matches by deviceId instead):

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 queries 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,
    items: [{ 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, so retrying a request that failed is safe - a repeat of an order that was already accepted is skipped, returned in response.skipped, and never written twice. Handle errors per-event, not per-batch:

async function sendConversion(event: SumidataEvent) {
  try {
    const res = await axios.post(URL, { projectId, deviceId, 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 }
  }
}

• 200 with skipped - invalid or duplicate events were dropped per-event; inspect response.skipped, don't retry the batch.
• 200 with status: "quota_exceeded" - your plan's monthly session quota is used up and nothing was stored; resend once quota is available again.
• 4xx (envelope errors - bad deviceId, missing IDs) - don't retry; fix the request.
• 5xx - requeue with exponential backoff. Exception: a projectId that is not a UUID, or a body over 64 MB, also returns 500 - fix the request instead.
• 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=YOUR_PROJECT_ID
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. The browser SDK also calls /sdk/chat/* (chat widget) and /sdk/heatmaps/screenshot (heatmap snapshots) - those are not for server use.

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 per project; a repeat (stored or earlier in the same batch) is skipped and returned in response.skipped
  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; omitted = sdk, which requires sessionId)
    events: Event[] - keep under 100 per batch
  response: { status: "ok", skipped?: [{ index, name, errors }], warnings?: [{ index, orderId, code, dropped, message }] }
  other_responses: { status: "replay_full", reason: "size_limit" } (replay chunk over 50 MB; events still stored) · { status: "quota_exceeded" } (monthly session quota used up; nothing stored)

event_fields:
  required: [name]
  conversion_required: [orderId] (+ totalAmount - revenue 0 without it; currency recommended)
  pricing: [totalAmount (order net, the only revenue source), currency, discountAmount, couponCode]
  items: Item[] on the purchase, max 200; Item = { productId (required), productName, productCategory, quantity (int 1–4294967295, default 1), unitPrice (≥ 0 and < 10^16, default 0) }; invalid or extra items are dropped with a warning, the order is kept
  one_event_per_order: product fields at the top level of a purchase → event skipped ("Send products inside items[]: one event per order")
  lifecycle: [isPrimarySale, timestamp (ms since epoch)]
  other: [source (overrides the envelope source for this event), url]
  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: one of 98 named surfaces (see Product events guide)
  _feature: regex ^[a-z0-9_]+$
  error_shape: 400 { "errors": { "<field>" | "_general": ["<message>"] } } - envelope only; per-event problems go to skipped
  skipped_shape: { "status": "ok", "skipped": [{ "index": i, "name": "…", "errors": { "<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)