Why send conversions from the server
The Gravity pixel records page views and detects some conversions in the browser. A server event is more reliable for events that your backend confirms:- Delivery: the event does not depend on the browser.
- Data: you can add customer email, phone, order details, and line items that the frontend does not have.
- Deduplication: an
event_idmakes sure that Gravity counts the same conversion only once. - Offline conversions: you can send phone calls, in-store purchases, and CRM events.
How it works
- The Gravity pixel runs on your site and records the attribution context.
- At the conversion, your frontend reads
window.gravityPixel.getCAPIData(). It sends the result to your backend with the order. - Your backend confirms the action. Then it calls
POST /gateway/eventswith the pixel data and the conversion details.
Before you start
- A Gravity advertiser account.
- Your Gravity API key. Find it in the Gravity dashboard in Settings → Organization. Only an owner or admin of the organization can see it. The API key is not the same as your pixel ID.
- The Gravity pixel on your site, if you want browser attribution. See Pixel setup.
- A backend that can keep the API key secret.
Step 1: Install the pixel
Add the pixel to every page, if it is not there yet:Step 2: Read the pixel data at the conversion
When the user completes a conversion, callgetCAPIData(). Send the result to your backend with the order:
You can call
getCAPIData() at any time after the pixel loads. Before the user gives consent, it returns null, so keep the || {} fallback. If the user did not arrive from a Gravity ad, the attribution fields are null. Gravity still records the conversion, but it does not attribute it to an ad.If you do not use the pixel, read every Gravity parameter from the landing page URL and store it. See Click IDs on the landing page.Step 3: Send the conversion from your backend
Node.js helper
On Node.js 20 or later, install the same package used by the Tracking CLI. Import its server-only entry point in your backend, never in browser or mobile code:GRAVITY_API_KEY in your server’s environment. After your backend confirms the action, call track():
req accepts an Express/Node request or a Fetch Request. If your handler has already read the body, pass gravity from that parsed body as shown above. track() fills the event timestamp and website action source, reads available request context, hashes email and phone, and sends the event with a two-second default timeout. It resolves to { ok, eventId, status?, eventStatus?, testMode?, error? } instead of throwing, so a tracking failure does not fail the business action.
With orderId, the default event ID is <eventName>:<orderId>. For other actions, supply a stable eventId. Keep the original eventTime on retries. Do not put email or other personal data in the event ID. Where the browser also sends the same event, give both senders the same event ID.
CommonJS uses the same entry point:
gravity: gravityMetadata(body.gravity), using gravityMetadata from @gravity-ai/tracking/server. For subscription checkout, also save it in subscription_data.metadata. The helper keeps the click IDs and page URL within Stripe’s 500-character metadata value limit. In the confirmed payment webhook, pass the saved value as gravity, the provider event’s original time as eventTime, and a stable object ID as eventId; the webhook request itself has no browser attribution.
The server entry point does not load the CLI, parser or native keyring. Server-only deployments can install with npm install --omit=optional to exclude the optional OS keyring dependencies. Saved CLI login then needs a normal install; API-key authentication through GRAVITY_API_KEY still works without keyring, and credentials are never saved to a plaintext file.
Direct API integration
Add your order details to the pixel data. Then send aPOST request to the Gravity gateway.
You can send email and phone in plaintext. The API normalizes and hashes them. If you hash an email yourself, remove the spaces at the start and end, and change it to lowercase. Then hash its UTF-8 bytes with SHA-256.
"test_event_code", so Gravity validates the event but does not record a conversion. Remove test_event_code when you go live.
The response is HTTP 200 with a status for each event. See Response.
Request reference
POST https://api.trygravity.com/gateway/events
Authentication
Send your API key in a request header, either one of these:401 with API key required. If the key is not valid, the response is 401 with Invalid API key.
Request body
Event fields
Event types
Gravity also knows these standard names:
AddPaymentInfo, AddToWishlist, SubmitApplication, ViewContent, Search, CustomizeProduct, FindLocation, Donate, PageView, AppInstall, AppOpen, and InAppPurchase.
You can also send a custom event name, for example "event_name": "DownloadWhitepaper".
User data fields
Attribution fields (from the pixel)
getCAPIData() adds these fields to user_data:
Send the
user_data object from getCAPIData() without changes, on every event. Don’t copy single fields out of it: Gravity needs the full set to attribute the conversion.
Click IDs on the landing page
When a user clicks a Gravity ad, Gravity sends them to your landing page and adds the click IDs to the URL as query parameters:
Gravity keeps the query parameters that are already in your landing page URL, and it also adds the UTM parameters that you set on the campaign.
The pixel reads these parameters and stores them, so
getCAPIData() returns them on later pages. Passing getCAPIData().user_data to your backend without changes is the easiest way to send all of them.
If you do not use the pixel, capture the parameters yourself:
- When the user lands, read every Gravity parameter in the URL:
grclid,grcpid,grpuid,gradid,grsig,graid, andoppref. Store each one that is present. - Persist them with the user’s session, and with the user’s account when they sign up, so that you still have them for events days or weeks later.
- Send all of the stored parameters in
user_dataon every conversion event.
grclid. Send every Gravity parameter that you stored.
If your tracking system needs the click ID in a parameter with a different name, put the {grclid} macro in your landing page URL or in a UTM value, for example https://yoursite.com/landing?subid={grclid}. Gravity replaces the macro with the click ID. Gravity also adds the grclid parameter.
Gravity click parameters
When a user clicks a Gravity ad, the landing page URL has the Gravity click parameters (grclid, grsig, grcpid, grpuid, gradid). Some clicks also carry graid, and some ad networks also pass oppref. Capture every parameter, store it, and send all of them with each conversion.
oppref alone does not attribute a conversion in Gravity. Send it together with a Gravity identifier such as grclid or grcpid.
Send the Gravity IDs on every event
Device context (from the pixel)
getCAPIData() also returns a client_context object. It contains device and browser signals, for example:
Send the full
client_context object from your frontend to your backend. Then add it to the CAPI request without changes. Gravity uses these signals for attribution and bot detection.
Customer identity (from your backend)
Add these fields on your backend. Sendem and client_ip_address on every event where you have them. They are expected on each event, not optional extras. Send the other fields when you collect them:
You can send
em, ph, fn, and ln as plaintext. Gravity normalizes them and hashes them with SHA-256 for storage. A hashed value must be a 64-character hex string. Before you hash, trim and lowercase emails, and keep only the digits of phone numbers.Custom data
Response
A normal request returns HTTP 200:accepted for each event. Gravity stores and attributes the events in the background. In this response, attributed is always false, because attribution occurs later. Test mode processes the events at once and returns the other statuses.
Errors
Deduplication
Gravity deduplicates events byevent_id and event_name in a 48-hour window. Gravity does not deduplicate an event that has no event_id.
- Use one stable ID for each confirmed action. Your order ID is a good choice.
- When you retry, send the same
event_id,event_name, andevent_time. - If the pixel and your server both send the same conversion, use the same event name and ID in both.
Batch events
You can send up to 1,000 events in one request. Add more objects to thedata array. The normal response only confirms that Gravity accepted the events. Look in Events Manager to make sure that the events arrived.
Verify the integration
1
Send a test event
Send a request with
"test_event_code": "TEST123". A valid event returns "status": "test_ok". Gravity does not store a conversion in test mode.2
Pass a test in Events Manager
Run the CAPI test in Events Manager for each event you want to use in a campaign. See Pass a test in Events Manager.
3
Send a real event
Remove
test_event_code. Send a confirmed conversion from your backend. The response is HTTP 200 with "status": "accepted".4
Look at the dashboard
Open Events Manager. Find a recent event on the Conversions API row. Then look for the conversion in your reports. An event can arrive and not match a Gravity ad.
Pass a test in Events Manager
A passed test unlocks the event for Conversions and CPA campaigns before any live event arrives. A test code that you make up, such asTEST123, checks the payload but doesn’t unlock the event.
- In Events Manager, select Set up tracking.
- In the CAPI test, enter the exact event name that your backend sends, then select Start test.
- Copy the
test_event_codefield that Events Manager shows. Add it at the top level of your CAPI request. - Trigger the event from your backend. Keep Events Manager open until it shows Test passed.
- Remove the
test_event_codefield from your request.
Check event quality
Events Manager scores the CAPI events of each event type from 0 to 10. The score measures how many of the signals that Gravity uses for matching and attribution your events carry. It doesn’t measure confirmed matches. To see it, open Events Manager and find the event type in the event list. Select its score to open the details.
The details list each signal with the share of events that include it:
Each signal shows Good (80% of events or more), Low (30% or more), or Missing (less than 30%). Time to send shows the median time from the action to Gravity receiving the event, rated Good, Slow, or Late by the share of events that arrive within an hour. Malformed email or phone hashes also lower the score.
Under Next step, the details show the one change that would raise the score most, for example sending an email hash or a stable
event_id. No changes needed means there is nothing to fix.
The score covers the last 7 days of live CAPI events. Test events don’t count. The score refreshes up to once an hour, so a change to your integration can take an hour to show.
Troubleshoot
Next
Pixel setup
Install the Gravity pixel on your site.