Sending Conversions

Pick Your Method

You can mix them. A common setup: geoswap.track("lead") on the form's thank-you page, then your CRM sends qualified and signed later through the API, linked to that lead. Whichever you use, keep the GeoSwap script on your site: credit goes to visits, and the script (along with clicks on GeoSwap short links) is what records them.

On Your Site: geoswap.track()

Once the GeoSwap script is on the page, call geoswap.track() when the conversion happens. It sends the visitor id and the GeoSwap short-link click id along automatically.

<script>
  window.geoswap = window.geoswap || { q: [], track: function () { this.q.push(arguments); } };
  // On your thank-you page, after the GeoSwap script tag
  geoswap.track("purchase", {
    id: "order-1001",     // your order or lead id: the same id is only counted once
    value: 49.99,         // optional, in currency units
    currency: "USD",      // optional, ISO 4217
    email: "jane@example.com" // optional, hashed on arrival, never stored raw
  });
</script>

The default install snippet loads with defer, so a geoswap.track() call placed right after the tag can run before the script has — add this stub first, every time. It's harmless once GeoSwap has loaded: calls queue up and the script drains the queue in order as soon as it's ready.

<script>
  // Safe to call before geoswap.js has loaded: calls are queued and sent in order
  window.geoswap = window.geoswap || { q: [], track: function () { this.q.push(arguments); } };
  geoswap.track("lead", { id: "form-8812" });
</script>

• Only people count: bot traffic is dropped.
• If your workspace only allows listed sites, conversions only count from those sites.
• GeoSwap accepts up to 2,000 conversions per workspace per hour from geoswap.track() and the Shopify pixel combined; extras are dropped. Send bigger volumes through the API.

Forms and Your CRM: Hidden Fields

When a form feeds your CRM, the conversion usually happens later (a lead gets qualified, a deal gets signed). To connect it back to the visit, add hidden inputs named gs_vid, gs_c and gs_r. The GeoSwap script fills in the ones that exist (it never adds inputs to your forms), so the values are saved on the CRM record. Send them back as visitor_id, click_id and contact_id with the API.

<form action="/contact" method="post">
  <input name="email" type="email" />
  <!-- GeoSwap fills these in; your CRM stores them with the lead -->
  <input type="hidden" name="gs_vid" />
  <input type="hidden" name="gs_c" />
  <input type="hidden" name="gs_r" />
  <button type="submit">Send</button>
</form>

Building your own form handler? geoswap.ids() returns the same values as { vid, c, r }. Forms inside cross-origin iframes (some embedded HubSpot forms) can't be filled in; send the email address instead.

Shopify Checkout

Shopify's checkout and order confirmation page don't run theme scripts, so geoswap.track() can't see a purchase there. The GeoSwap custom pixel can: it sends each completed order as a purchase with its order id, total and currency, joined to the visitor's earlier visits. Copy it from Foundations → Sites & script in your dashboard (your Project ID is already in it) and paste it under Shopify Admin → Settings → Customer events. Step by step: Track purchases from checkout.

Store Funnel: Cart and Checkout Events

Add cart and checkout events to see them on Analytics → Funnel: product_viewed, add_to_cart, checkout_started and payment_info. Send them the same way as any other geoswap.track() call:

geoswap.track("add_to_cart");
// ...later, on your checkout page:
geoswap.track("checkout_started");

On Shopify, add product_added_to_cart and checkout_started to the same custom pixel as your purchase events (Shopify checkout above) — GeoSwap recognizes Shopify's and GA4's names for these events automatically (view_item, product_added_to_cart, begin_checkout, add_payment_info).

From Your CRM or Server: the API

POST https://api.geoswap.co/v1/conversions with an API key that has the conversions:write scope (Settings → API keys), or up to 500 at once with /conversions/batch. The API is the right choice for offline stages (qualified, signed, renewed), backfills of older conversions, and anything that happens away from the browser.

curl -X POST https://api.geoswap.co/v1/conversions \
  -H "Authorization: Bearer $GEOSWAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "event": "qualified",
  "external_id": "006Hs00001AbCdE",
  "parent_external_id": "00QHs00002XyZqR",
  "occurred_at": "2026-10-12T14:03:00Z",
  "visitor_id": "Xb3k9_Qm2LpA7vR1.20261003",
  "email": "jane@example.com",
  "value": 1200,
  "currency": "USD",
  "tags": {
    "market": "co"
  }
}'

• Link stages with parent_external_id (the lead behind a deal). They can arrive in any order, and a later stage shares the first stage's visits.
• Correct a conversion by sending it again with the same event and external_id. Change its time, value or identifiers and it's re-credited.
• Send occurred_at as when it really happened. Any age is accepted, but visits are only kept for 400 days, so very old conversions land on Unattributed.

Full field list, errors and limits: API reference. Ready-made setups for Salesforce, HubSpot and Zapier: CRM recipes.

Funnel Stages

Each stage is its own event and its own column in the report: lead, qualified, signed. Every stage is credited in full, so never add stages together (one journey with a lead and a signed deal would count twice). The report never shows a cross-event total for that reason.

Check It Worked

Conversions show up in Attribution as Processing first (Overview's Tracking health), and are credited within about three hours. To check a specific one, open Journeys and use Look up a conversion with its id: you'll see its stages, the visits it was matched to and the credit each one got under every model.