Skip to main content

Context API Object

Overview​

The context object captures the server-side environment data for each event sent through the API. It preserves the original user interaction details (user agent, IP address, URLs) that are required for accurate attribution and analytics in server-to-server implementations.

Properties​

  • environment (required) — prod for live data, dev for testing. Events sent with dev are logged but not processed. Using the /test endpoint suffix forces dev regardless of this value.
  • data_source — identifies the origin system (e.g. website, app, admin, phone, crm). Free-form string, use consistent naming.
  • user_agent — the original browser user agent string, preserved from the user's session
  • override_ip — the original user's IP address. If not provided, the IP from the request headers is used automatically.
  • url — the page URL where the action occurred. If not provided, a fallback is generated from your account configuration.
  • landing_url — the first page URL of the user's session
  • referrer_url — the external URL that brought the user to the site

Complete Reference​

context object

environment string required

info

Allowed values: prod, dev

environment: "prod"

data_source string required

info

Recommended values:

  • for website events: website
  • for admin manual added orders events: phone or admin
  • for app events: app
  • for marketplace events : marketplace. (You can replace "marketplace" word with real marketplace name.)
data_source: "website"

user_agent string recommended

info

User-Agent string from a browser when the event occurs

user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36"

override_ip string recommended

info

Ip address. Support ipv4 or ipv6. Recommended ipv6 if exists.

override_ip: "123.123.123.99"

url string recommended

info

URL of the page where the event occurred

url:"https://shop.example.com/thankyou-page"

landing_url string recommended

info

URL of the first page visited in the session where the event occurred

landing_url:"https://shop.example.com/landing-page?query=abc"

referrer_url string recommended

info

URL of the external referring site

referrer_url:"https://google.com"

Examples​

{
  "environment": "prod",
  "data_source": "website",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36",
  "override_ip": "203.0.113.45",
  "url": "https://shop.example.com/checkout/confirmation",
  "landing_url": "https://shop.example.com/products/laptop?utm_source=google&utm_medium=cpc",
  "referrer_url": "https://google.com/search"
}

Collecting Context Data (PHP)​

Context data must be collected during the original user session and preserved for later webhook transmission:

// Collect during user session
$contextData = [
    'user_agent' => $_SERVER['HTTP_USER_AGENT'] ?? '',
    'override_ip' => $_SERVER['HTTP_X_FORWARDED_FOR'] ?? $_SERVER['REMOTE_ADDR'] ?? '',
    'url' => (isset($_SERVER['HTTPS']) ? 'https' : 'http') . '://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'],
    'landing_url' => $_SESSION['landing_url'] ?? '',
    'referrer_url' => $_SESSION['referrer_url'] ?? ''
];

// Store in session/database for later use in webhook payload
$_SESSION['tracking_context'] = $contextData;
// Later, when sending the webhook (e.g. on order completion)
$payload = [
    'event' => [ /* ... */ ],
    'context' => array_merge([
        'environment' => 'prod',
        'data_source' => 'website'
    ], $_SESSION['tracking_context']),
    // ...
];

Best Practices​

  • Preserve original context — always use the original user's user agent and IP address, not the server's
  • Collect early — capture context data at session start (landing URL, referring URL) and store for later use
  • Use dev for testing — set environment to dev during integration to validate payloads without processing
  • Consistent data sources — use a standardized naming convention for data_source across your implementations
  • HTTPS only — always transmit context data over HTTPS