Server-to-Server Integration

Send event and conversion data directly from your server to Adverfly — no browser pixel required.

Endpoint

POST https://b.adverfly.com/e
Content-Type: application/json

Required Fields

Field	Type	Description
`store_id`	number	Your Adverfly workspace ID
`event_type`	string	"event" for funnel steps (add_to_cart, checkout) or "conversion" for end goals (purchase, lead)
`name`	string	Event name (e.g. "add_to_cart", "purchase")
`is_s2s`	boolean	Must be true for server-to-server requests
`ip`	string	Customer IP address (not your server IP)

ℹevent_type — a conversion is always the end goal of a customer journey (e.g. purchase, lead). Funnel steps like add_to_cart or initiated_checkout are event, not conversion.

⚠ip — required for S2S. Without it, the endpoint falls back to the caller's IP (your server). This means all customers would be identified as a single visitor.
keys — not required, but essential for accurate visitor identification. Without keys, visitors can only be identified by IP which is significantly less accurate. Send all available identifiers (Shopify Client ID, _ga, _fbp).

Recommended Fields

Field	Type	Description
`keys`	string[]	All available visitor keys (Shopify Client ID, _ga, _fbp) — essential for accurate visitor identification
`hostname`	string	Shop domain, e.g. "www.myshop.com"
`pathname`	string	URL path, e.g. "/products/sneakers"
`visitor_ts`	number	Unix timestamp in milliseconds
`store_currency`	string	Store currency, e.g. "EUR"
`store_timezone`	string	Store timezone, e.g. "Europe/Berlin"
`entry_meta.key`	string[]	All available click ID names for attribution (see below)
`entry_meta.value`	string[]	Click ID values (same order as keys, empty string if unavailable)

Event: "add_to_cart"

{
  "store_id": 123456,
  "event_type": "event",
  "name": "add_to_cart",
  "is_s2s": true,
  "ip": "185.32.100.42",
  "keys": [
    "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "GA1.2.123456789.1711234567",
    "fb.1.1711234567890.123456789"
  ],
  "hostname": "www.myshop.com",
  "pathname": "/products/sneakers",
  "visitor_ts": 1711234567890,
  "store_currency": "EUR",
  "store_timezone": "Europe/Berlin",
  "entry_meta.key": [
    "obclid",
    "gclid",
    "gbraid",
    "fbclid",
    "_fbp",
    "_fbc",
    "ttclid",
    "sclid",
    "epik",
    "twclid",
    "msclkid",
    "li_fat_id"
  ],
  "entry_meta.value": [
    "",
    "",
    "",
    "fb.1.abc123",
    "fb.1.1711234567890.123456789",
    "",
    "",
    "",
    "",
    "",
    "",
    ""
  ]
}

Event: "initiated_checkout"

{
  "store_id": 123456,
  "event_type": "event",
  "name": "initiated_checkout",
  "is_s2s": true,
  "ip": "185.32.100.42",
  "keys": [
    "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "GA1.2.123456789.1711234567",
    "fb.1.1711234567890.123456789"
  ],
  "hostname": "www.myshop.com",
  "pathname": "/checkout",
  "visitor_ts": 1711234567890,
  "store_currency": "EUR",
  "store_timezone": "Europe/Berlin",
  "entry_meta.key": [
    "obclid",
    "gclid",
    "gbraid",
    "fbclid",
    "_fbp",
    "_fbc",
    "ttclid",
    "sclid",
    "epik",
    "twclid",
    "msclkid",
    "li_fat_id"
  ],
  "entry_meta.value": [
    "",
    "",
    "",
    "fb.1.abc123",
    "fb.1.1711234567890.123456789",
    "",
    "",
    "",
    "",
    "",
    "",
    ""
  ]
}

Event: "purchase"

{
  "store_id": 123456,
  "event_type": "conversion",
  "name": "purchase",
  "is_s2s": true,
  "ip": "185.32.100.42",
  "keys": [
    "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "GA1.2.123456789.1711234567",
    "fb.1.1711234567890.123456789"
  ],
  "hostname": "www.myshop.com",
  "pathname": "/checkout/thank-you",
  "visitor_ts": 1711234567890,
  "store_currency": "EUR",
  "store_timezone": "Europe/Berlin",
  "transaction_id": "order-12345",
  "transaction_gross_revenue": 9900,
  "transaction_shipping_costs": 499,
  "transaction_tax": 1583,
  "transaction_currency": "EUR",
  "transaction_discount_code": "SAVE10",
  "transaction_city": "Berlin",
  "transaction_country_code": "DE",
  "customer_id": "customer@email.com",
  "is_new_customer": 1,
  "transaction_items": [
    {
      "transaction_item_id": "SKU-001",
      "transaction_item_name": "Nike Air Max",
      "transaction_item_price": 4950,
      "transaction_item_tax": 0,
      "transaction_item_quantity": 2
    }
  ],
  "entry_meta.key": [
    "obclid",
    "gclid",
    "gbraid",
    "fbclid",
    "_fbp",
    "_fbc",
    "ttclid",
    "sclid",
    "epik",
    "twclid",
    "msclkid",
    "li_fat_id"
  ],
  "entry_meta.value": [
    "",
    "CjwKCAjw...",
    "",
    "fb.1.abc123",
    "fb.1.1711234567890.123456789",
    "",
    "",
    "",
    "",
    "",
    "",
    ""
  ]
}

Conversion Fields (Purchase Only)

Field	Type	Description
`transaction_id`	string	Order ID (hashed server-side, used for deduplication)
`transaction_gross_revenue`	number	Total revenue in cents (€99.00 = 9900)
`transaction_shipping_costs`	number	Shipping costs in cents
`transaction_tax`	number	Tax amount in cents
`transaction_currency`	string	Customer currency (auto-converted to store currency)
`transaction_discount_code`	string	Discount code(s)
`transaction_city`	string	Shipping city
`transaction_country_code`	string	2-letter ISO code ("DE", "AT", "CH")
`customer_id`	string	Customer email or ID (hashed server-side)
`is_new_customer`	number	1 = new, 0 = returning
`transaction_items`	array	Line items (see purchase example above)

ℹAll monetary values must be in cents. €99.00 = 9900, €4.99 = 499.

Keys — Visitor Identification

Send all available visitor identifiers. The more keys you provide, the better the cross-session visitor stitching. Keys are hashed server-side — send plain text.

Key	Source	Description
`Shopify Client ID`	Shopify	Unique visitor ID from Shopify (event.clientId)
`_ga`	Google Analytics	GA Client ID cookie value
`_fbp`	Meta Pixel	Meta browser ID cookie value

Entry Meta — Click IDs for Attribution

Send all click IDs on every event (not just purchase). entry_meta.key and entry_meta.value must be the same length — use empty string if not available.

Key	Platform
`obclid`	Outbrain
`gclid`	Google Ads
`gbraid`	Google Ads (App)
`fbclid`	Meta
`_fbp`	Meta Browser ID
`_fbc`	Meta Click ID Cookie
`ttclid`	TikTok
`sclid`	Snapchat
`msclkid`	Microsoft Ads
`epik`	Pinterest
`twclid`	Twitter / X
`li_fat_id`	LinkedIn

Hashing of Personal Data

Personal data such as customer_id (e.g. email address) and transaction_id can be sent either as plain text or pre-hashed (SHA-256). If you send plain text, Adverfly will automatically hash these values server-side before storage. No personal data is stored in plain text.

Field	Accepted formats
`customer_id`	Plain text (e.g. "kunde@email.com") or SHA-256 hash
`transaction_id`	Plain text (e.g. "order-12345") or SHA-256 hash

Important Notes

All monetary values in cents — €99.00 = 9900
ip must be the end customer's IP — without it, your server's IP is used and all events are attributed to a single visitor
keys are hashed server-side — send plain text
Response 200 = event accepted, 400 = validation error (check response body)
Events are fire-and-forget — tracking should never block your checkout flow

Need help? Contact us at team@adverfly.com