Attribution Metadata Fields

The SDK automatically collects attribution metadata — device info, referrer, landing page, timestamps — and sends it with every order. For this data to flow through, your store must have matching metadata field definitions configured in NEXT Settings.

All 9 fields below must be added in Settings → Metadata before the SDK will include them on orders. Missing fields are silently dropped — no error, just missing data.

Dashboard Setup

Go to NEXT Dashboard → Settings → Metadata (/dashboard/settings/metadata/)
Add each field from the table below with object: Attribution
Set enable_export: true on all fields

This is a one-time-per-store setup. Metadata definitions are store-level — all campaigns on a store share them. Configure these when launching your first campaign, then verify on subsequent campaigns.

Required Fields

All fields use object: "attribution" and enable_export: true.

Key	Type	Description
`conversion_timestamp`	integer	Epoch milliseconds when the conversion event fired
`device`	text	Full user-agent string
`device_type`	text	Device classification: `desktop`, `mobile`, or `tablet`
`domain`	text	Domain where the conversion occurred
`landing_page`	text	Page URL where the customer landed or converted
`referrer`	text	Full referrer URL including tracking parameters
`sdk_version`	text	Campaign Cart SDK version that processed the order (e.g., `0.3.10`)
`timestamp`	integer	Order submission timestamp in epoch milliseconds
`user_ip`	text	Customer IP address at time of order (IPv4 or IPv6)

Field Details

conversion_timestamp vs timestamp — Two separate timestamps exist intentionally. conversion_timestamp records when the conversion event fired (e.g., the customer clicked "Buy Now"), while timestamp records when the order was actually submitted. The gap between them captures checkout completion time.

device_type — Determined by the SDK using viewport size and user-agent heuristics, not a server-side parser. Values are always one of desktop, mobile, or tablet.

referrer — Preserves the full URL including all tracking parameters (click IDs, campaign IDs, sub-tracking values). This is intentional — truncating the referrer would lose affiliate and ad network attribution data. Values can exceed 1000 characters with nested tracking parameters from affiliate networks.

user_ip — Captures the customer's IP address, not the server IP. IPv6 addresses (e.g., 2601:441:4580:5760:b4c4:2214:9d19:2e54) are common. Any downstream systems consuming this field must handle both formats.

API Provisioning

As an alternative to the dashboard UI, you can create metadata field definitions via the Admin API.

Endpoint: POST {STORE}/api/admin/metadata/

curl -X POST "$NEXT_STORE/api/admin/metadata/" \
  -H "Authorization: Bearer $NEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SDK Version",
    "object": "attribution",
    "key": "sdk_version",
    "type": "text",
    "validations": [{"type": "maximum_length", "value": 50}],
    "enable_export": true,
    "enable_filter": false
  }'

Returns 201 with the created record. Repeat for each of the 9 fields, adjusting name, key, type, validations, and enable_filter per the table above. For integer fields (conversion_timestamp, timestamp), omit the validations array.

API version header gotcha: Do not send X-29next-API-Version: 2024-04-01 on POST /api/admin/metadata/. Records created with that header return 201 but are filtered out of the versioned GET list and won't appear in the dashboard UI. Omit the version header on POST; include it on GET.

Example Payload

When all fields are configured, the SDK sends attribution metadata like this with each order:

{
  "conversion_timestamp": 1776302762386,
  "device": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.6 Safari/605.1.15",
  "device_type": "desktop",
  "domain": "osmo-official.com",
  "landing_page": "https://osmo-official.com/us/checkout-flashlight-v2",
  "referrer": "https://osmo-official.com/us/flashlight-v4?clickid=69e039c421910a0bc1ffecc6&rtkcid=...",
  "sdk_version": "0.3.10",
  "timestamp": 1776302818758,
  "user_ip": "2601:441:4580:5760:b4c4:2214:9d19:2e54"
}

Gotchas

Silently dropped fields — If a field is not defined in Settings → Metadata, the SDK will not include it on orders. There is no error or warning — the data simply won't appear.
Referrer length — The referrer field can exceed 1000 characters due to nested tracking parameters from affiliate networks and ad platforms. The recommended max_length of 2000 accommodates this.
Epoch milliseconds — Both conversion_timestamp and timestamp are epoch milliseconds, not seconds. Divide by 1000 to get Unix seconds.
IPv6 addresses — The user_ip field commonly contains IPv6 addresses. Ensure downstream systems, reports, and exports handle both IPv4 and IPv6.
SDK-determined device type — device_type is classified by the SDK based on viewport and user-agent heuristics, not by a server-side parser.