An integration sends the conversions. It does not replace the Gravity Pixel on your website. The Pixel records the visit that led to the conversion. Shopify is the exception: the Shopify app installs its own Pixel on your storefront.
Before you start
- Access to the Gravity dashboard as a member of your advertiser account.
- Admin access to your Shopify store, Stripe account, or Cal.com account.
- For Stripe and Cal.com: the Gravity Pixel on your website.
- For Cal.com: your advertiser API key from Settings → Organization.
Shopify
The Gravity Shopify app installs a Shopify web pixel on your storefront. It also subscribes to theorders/paid webhook. Gravity then gets purchase events from the checkout and from your Shopify server.
In Events Manager → Set up tracking, tell Gravity how your store is built:
- Fully hosted on Shopify: the app tracks Purchase, and setup needs no code changes. Events Manager shows only the Shopify app steps, not the code installers.
- Custom website with Shopify checkout: the app tracks Purchase. To track other actions on your own site, use the Tracking CLI or the Conversions API.
1
Open the integrations settings
In the Gravity dashboard, go to Settings → Organization. In the Integrations section, select Connect on the Shopify row.
2
Approve the app in Shopify
Follow the dialog to install the Gravity app in your Shopify store. Approve the permissions that the app requests.
3
Wait for verification
Gravity turns on the web pixel and starts to sync your product catalog. The Shopify row shows Pending until Gravity receives a valid event from the store. Then it shows Connected.
purchase conversions, with the order value and currency. The checkout pixel and the orders/paid webhook use the Shopify order ID for deduplication. Gravity counts each order one time.
Test the Shopify connection
After you connect the app, you can test the connection before your first paid order. Only an owner or admin of the organization can send a test.- In Events Manager, select Set up tracking.
- Under Shopify purchases, select Send test purchase. If you connected more than one store, each store has its own button.
- Wait for Test purchase received.
You do not need the manual
gr-pix.js snippet on your Shopify storefront. Add it to each page outside Shopify where visitors land first, for example your marketing site or blog.Stripe
Connect Stripe with the Gravity Stripe app. You do not need to copy an API key, create a webhook endpoint, or paste a signing secret.- Go to Settings → Organization.
- In the Integrations section, select Connect on the Stripe row. The Connect Stripe dialog opens.
- Select Authorize Gravity in Stripe with one-click and authorize the Gravity app in Stripe.
- Return to Gravity and make a test purchase to verify the connection.
If the Stripe connection is unavailable, try again later. New manual webhook connections are no longer supported. Existing manual endpoints remain valid and continue to process signed events. You can still view their status and disconnect them in Gravity. After disconnecting, use the app to connect again.
Pass attribution to Stripe
When you create the Checkout Session, add every Gravity field fromgetCAPIData().user_data to its metadata: grclid, grcpid, grpuid, gradid, grsig, graid, and oppref. Copy every field that has a value, not only grclid. If you can’t use metadata and client_reference_id is empty, put the IDs in client_reference_id in the packed form gr|<grclid>|<grcpid>|<grpuid>|<gradid>. Prefer metadata, because client_reference_id can’t carry grsig, graid, or oppref.
For subscription Checkout, add the same flat fields to both Checkout metadata and subscription_data.metadata. The native Stripe connection reads the Subscription metadata that Stripe copies onto the first invoice, and Checkout metadata alone does not set it. If you create the Subscription directly, put the fields in its metadata. For Checkout, run this in your server-side Checkout handler, where gravity is the getCAPIData() result your browser sent:
- A real purchase from an ad click shows up in Events Manager, matched to the right campaign.
- Retries, and a subscription Checkout plus its first invoice, count as one conversion.
- You don’t count test events as proof. They only show that events arrive.
Cal.com
Use Cal.com for demo bookings and consultations. Cal.com sends booking events directly to Gravity.1
Add a webhook in Cal.com
In Cal.com, go to Settings → Developer → Webhooks → New. Use this subscriber URL:Under Custom headers, add a header named
X-API-Key with your advertiser API key as the value. Find the key in the Gravity dashboard under Settings → Organization.2
Use the same key as the signing secret
Paste the same API key into the Secret field in Cal.com. Gravity verifies the
x-cal-signature-256 HMAC with it. If the verification fails, Gravity still records the booking, but marks it as unverified.3
Select your triggers
Subscribe to the booking events that you want to track. Each trigger becomes a different conversion event:
Pass attribution to Cal.com
The Pixel gets the Gravity click IDs from the URL of your booking page. Pass them to Cal.com as bookingmetadata.attribution: grclid, grcpid, grpuid, gradid, grsig, and graid. Then Gravity can connect each booking to the ad that caused it. Pass every field that has a value, not only grclid.
Check what is connected
The Dashboard API lists your connected Shopify stores:Troubleshoot
Next steps
Conversions API
Send conversions from your own backend.
Advertiser pixel
Install the Pixel on your website. Shopify storefronts do not need it.