Server-side conversions (CAPI)

Why server-side?

The Gravity pixel tracks page views and auto-detects some conversions client-side. But for the highest fidelity — especially for purchases, signups, and other backend-confirmed events — sending conversions server-to-server is more reliable:

More reliable — server-side calls aren’t affected by browser extensions or network conditions
Richer data — attach customer email, order details, and line items your frontend doesn’t have
Deduplication — use event_id to prevent double-counting across pixel and server events
Offline conversions — attribute phone calls, in-store purchases, and CRM events back to ads

How it works

The Gravity pixel runs on your site and captures attribution context automatically
On conversion, your frontend reads window.gravityPixel.getCAPIData() and sends it to your backend alongside the order
Your backend calls POST /gateway/events with the pixel context plus server-side details (email, order total, line items)

Step 1 — Install the pixel

If you haven’t already, add the pixel to every page:

<script>
  !function(w,d,t,u,n,a,m){w['GravityPixelObject']=n;w[n]=w[n]||function(){
  (w[n].q=w[n].q||[]).push(arguments)},w[n].l=1*new Date();a=d.createElement(t),
  m=d.getElementsByTagName(t)[0];a.async=1;a.src=u;m.parentNode.insertBefore(a,m)
  }(window,document,'script','https://code.trygravity.ai/gr-pix.js','gravity');
  gravity('init', 'YOUR_ADVERTISER_ID');
</script>

Step 2 — Read pixel data on conversion

When the user completes a conversion (purchase, signup, etc.), call getCAPIData() and pass the result to your backend:

// On your checkout confirmation / thank-you page
var capiData = window.gravityPixel.getCAPIData();

fetch('/api/complete-order', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    order_id: 'order-123',
    total: 99.99,
    currency: 'USD',
    email: 'customer@example.com',
    gravity: capiData
  })
});

getCAPIData() returns a ready-to-merge object:

{
  "user_data": {
    "grclid": "abc-click-id",
    "grcpid": "campaign-uuid",
    "grpuid": "publisher-uuid",
    "gradid": "ad-uuid",
    "grsig": "signature",
    "graid": "attribution-id",
    "visitor_id": "gr-visitor-id",
    "session_id": "gr-session-id",
    "client_user_agent": "Mozilla/5.0 ..."
  },
  "event_source_url": "https://yoursite.com/checkout",
  "client_context": {
    "timezone": "America/New_York",
    "screen": { "width": 1920, "height": 1080, "color_depth": 24 },
    "viewport": { "width": 1440, "height": 900 },
    "platform": "macOS",
    "connection": { "type": "4g", "downlink": 10 }
  }
}

getCAPIData() is safe to call at any time after the pixel loads. If the user arrived via a Gravity ad click, the attribution fields will be populated. If not, they return null — the conversion still records, it just won’t be attributed to a specific ad.The client_context object includes device and environment signals (timezone, screen dimensions, platform) captured by the pixel. Pass the entire object through to your backend and include it in the CAPI request — Gravity uses these signals to improve attribution accuracy.

Step 3 — Send the conversion from your backend

Merge the pixel data with your order details and POST to the Gravity gateway. Pick your language:

import requests
import hashlib
import time

API_KEY = "YOUR_GRAVITY_API_KEY"  # From Settings → Organization

def hash_pii(value: str) -> str:
    """SHA-256 hash for PII. Or send plaintext — the API hashes it for you."""
    return hashlib.sha256(value.strip().lower().encode()).hexdigest()

def send_gravity_conversion(order, gravity_data):
    user_data = gravity_data.get("user_data", {})

    response = requests.post(
        "https://api.trygravity.ai/gateway/events",
        params={"api_key": API_KEY},
        json={
            "data": [{
                "event_name": "Purchase",
                "event_time": int(time.time()),
                "event_id": f"order-{order['id']}",
                "action_source": "website",
                "event_source_url": gravity_data.get("event_source_url", ""),
                "user_data": {
                    **user_data,
                    "em": [order["email"]],
                    "external_id": [str(order["customer_id"])],
                },
                "client_context": gravity_data.get("client_context"),
                "custom_data": {
                    "value": order["total"],
                    "currency": order.get("currency", "USD"),
                    "order_id": str(order["id"]),
                    "contents": [
                        {"id": item["sku"], "quantity": item["qty"], "item_price": item["price"]}
                        for item in order.get("items", [])
                    ],
                },
            }],
        },
    )
    return response.json()

Include "test_event_code": "TEST123" to validate your payload without recording a real conversion. Remove it when you go live.

Event types

Event name	When to fire
`Purchase`	Order completed
`Lead`	Form submission, demo request
`CompleteRegistration`	Account created
`Subscribe`	Subscription started
`StartTrial`	Free trial started
`InitiateCheckout`	Checkout started
`AddToCart`	Item added to cart
`Contact`	Contact form or phone call
`Schedule`	Appointment booked

Custom event names are also accepted (e.g., "event_name": "DownloadWhitepaper").

User data fields

Attribution (from pixel)

These are automatically included when you use getCAPIData():

Field	Description
`grclid`	Gravity click ID
`grcpid`	Campaign ID
`grpuid`	Publisher ID
`gradid`	Ad ID
`graid`	Attribution ID
`visitor_id`	Gravity visitor ID
`session_id`	Current session ID
`client_user_agent`	Browser user agent string

Device context (from pixel)

The client_context object is automatically included by getCAPIData(). It contains device and environment signals that improve conversion quality:

Field	Description
`timezone`	User’s timezone (e.g. `America/New_York`)
`screen`	Screen dimensions and color depth
`viewport`	Browser viewport dimensions
`platform`	OS platform (e.g. `macOS`, `Windows`)
`connection`	Network connection type

Pass the entire client_context object through from your frontend to your backend, then include it in the CAPI request — no manipulation is needed on your end. Gravity uses these signals to improve attribution accuracy.

Customer identity (from your backend)

Add these server-side for richer matching:

Field	Type	Description
`em`	`string[]`	Email address(es) — plaintext OK, auto-hashed before storage
`ph`	`string[]`	Phone number(s) in E.164 format
`fn`	`string`	First name
`ln`	`string`	Last name
`external_id`	`string[]`	Your system’s customer/user IDs

PII fields (em, ph, fn, ln) can be sent as plaintext — the API normalizes and SHA-256 hashes them before storage. No plaintext PII is ever persisted. If you prefer to pre-hash, send 64-character hex strings and the API will detect and accept them as-is.

Custom data

Field	Type	Description
`value`	`float`	Conversion value (e.g., order total)
`currency`	`string`	ISO 4217 currency code (default: `USD`)
`order_id`	`string`	Your order/transaction ID
`contents`	`object[]`	Line items: `{ id, quantity, item_price, title }`
`content_name`	`string`	Product or content name
`content_category`	`string`	Product category
`predicted_ltv`	`float`	Predicted customer lifetime value

Response

{
  "events_received": 1,
  "events_processed": 1,
  "events_errored": 0,
  "results": [
    { "event_id": "order-123", "status": "ok", "attributed": true }
  ],
  "test_mode": false
}

Status	Meaning
`ok`	Event processed and stored
`duplicate`	Already seen (same `event_id` + `event_name` within 48 hours)
`test_ok`	Validated but not stored (test mode)
`skipped`	User opted out
`error`	Processing failed — see `error` field

Deduplication

Events are deduplicated by event_id + event_name within a 48-hour window. Always include a unique event_id (e.g., your order ID) to prevent double-counting — especially if you fire both a pixel conversion and a server-side conversion for the same purchase.

Authentication

Pass your API key as a query parameter or Authorization header:

?api_key=YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Your API key is in Settings → Organization in the Gravity dashboard.

Batch events

Send up to 1,000 events per request by adding more objects to the data array. Each event is processed independently — partial failures don’t reject the batch.

Pixel setup

Install the Gravity pixel on your site.

Analytics

View conversion reports and ROAS.

Get started

Measure

Server-side conversions (CAPI)

Why server-side?

How it works

Step 1 — Install the pixel

Step 2 — Read pixel data on conversion

Step 3 — Send the conversion from your backend

Event types

User data fields

Attribution (from pixel)

Device context (from pixel)

Customer identity (from your backend)

Custom data

Response

Deduplication

Authentication

Batch events

Next

Pixel setup

Analytics

Get started

Measure

Documentation Index

​Why server-side?

​How it works

​Step 1 — Install the pixel

​Step 2 — Read pixel data on conversion

​Step 3 — Send the conversion from your backend

​Event types

​User data fields

​Attribution (from pixel)

​Device context (from pixel)

​Customer identity (from your backend)

​Custom data

​Response

​Deduplication

​Authentication

​Batch events

​Next

Pixel setup

Analytics

Why server-side?

How it works

Step 1 — Install the pixel

Step 2 — Read pixel data on conversion

Step 3 — Send the conversion from your backend

Event types

User data fields

Attribution (from pixel)

Device context (from pixel)

Customer identity (from your backend)

Custom data

Response

Deduplication

Authentication

Batch events

Next