How to

Attribution

Track conversions and attribute revenue to creators through their links and discount codes on a Custom OMS (non-Shopify) store.

Attribution connects a customer’s journey to the creator who referred them, so you can measure conversions and credit creators for the revenue they generate. For a Custom OMS (non-Shopify) store, your storefront records the customer journey and your order management system submits confirmed paid orders from your backend. Your commerce platform continues to manage checkout, discounts, payments, and fulfillment.

The required flow is: creator link → your storefront → checkout → browser checkout event plus authenticated order API request → attribution in Superfiliate.

Before you start with a Custom OMS

• Identify who can edit DNS, storefront code, checkout confirmation code, and the backend that receives confirmed payment/order notifications.
• Confirm the storefront and checkout hostnames, store currency, program rewards, attribution window, and test environment with Superfiliate. Custom order conversion processing currently requires the order currency to match the configured store currency.
• Create server-side credentials in Settings → Developers. The examples read them from SF_CLIENT_ID and SF_CLIENT_SECRET environment variables.

Keep API credentials on your backend. The public storefront script uses your shop identifier and does not need an API secret.

1. Connect your creator-link domain

Use a branded subdomain such as partners.yourstore.com, ideally on the same root domain as your store. A link such as https://partners.yourstore.com/JOHN identifies the creator before sending the customer to your store or creator landing page. Sharing the root domain also helps preserve tracking cookies.

In Settings → Custom Domain, add the CNAME and ownership TXT records shown in the app, verify them, then complete Connect domain. Follow Custom Domain Set Up for the current DNS instructions.

For help identifying your domain provider or checking CNAME and other DNS records, use the Domain Provider & Verification Guide.

The CNAME connects your creator-link hostname. A separate redirect destination setting chooses where customers go when Cobranded Landing Pages are disabled. For direct-to-store links, follow Choose where your creator links send shoppers. Keep tracking query parameters through every redirect. Connecting the domain does not install tracking or apply discounts on your checkout.

2. Install the script and track the customer journey

In Settings → Developers → Attribution script, copy your store’s script tag. You can also fetch it with GET /api/v1/attribution. Install it on every storefront page, including product pages, cart, checkout, and the order confirmation/thank-you page.

curl "https://api.superfiliate.com/api/v1/attribution" \
  -H "Authorization: Bearer $SF_CLIENT_ID:$SF_CLIENT_SECRET"

{
  "scriptTag": "<script defer src=\"https://superfiliate-cdn.com/storefront.js?shop=YOUR_SHOP_IDENTIFIER\"></script>",
  "version": "1"
}

Place the copied tag in the document head. Replace the example shop identifier with the tag copied from Developers:

<script defer src="https://superfiliate-cdn.com/storefront.js?shop=YOUR_SHOP_IDENTIFIER"></script>

Add the tracking calls to your existing storefront code, in a file or module you control. Run the JavaScript examples inside an async callback or module. The helper below waits until the SDK is available, then stores the SDK object in superfiliateSdk so you can call its methods directly. It returns immediately if the script has already loaded, or throws an error after 10 seconds if it remains unavailable:

async function waitForSuperfiliateSdk(timeoutMs = 10000) {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const sdk = window.$superfiliateStorefront?.sdk;
    if (sdk) return sdk;
    await new Promise((resolve) => setTimeout(resolve, 50));
  }

  throw new Error("Superfiliate SDK did not load. Check the storefront script.");
}

const superfiliateSdk = await waitForSuperfiliateSdk();
await superfiliateSdk.handlePageView();

Call handlePageView() while the original landing URL still contains its tracking parameters. The SDK reads Superfiliate’s UTM parameters, including utm_source and the encoded attribution data in utm_content. It also recognizes attributes[sf-origin] and attributes[sf-external-session-uuid] when present. Keep the parameters supplied by the creator link; you do not need to parse them yourself.

On an attributed visit, the SDK saves a cookie named sf_microsite_session. Its value is an anonymous UUID identifying the customer’s attribution session. It connects the customer’s visit to their later checkout; it does not contain their email or your OMS customer ID. The SDK sends external_access and main_store_access when applicable. No customer email or order data is needed for this call, and repeated navigation in the same session does not emit another store-entry event.

On a single-page application, also call the handler after route changes, before removing any new attribution parameters:

await superfiliateSdk.handlePageView();

After your OMS confirms the order is paid, call the checkout handler on the confirmation/thank-you page with your actual order data. The storefront script and page-view initialization above must have completed first. If this is a new page load, use the same readiness helper to initialize superfiliateSdk there before calling the handler. A click on Pay alone does not confirm payment.

await superfiliateSdk.handleCheckoutCompleted({
  id: "order-123",
  totalValue: "100.00",
  currency: "USD",
  discountCodes: ["JOHN"],
  customer: {
    id: "customer-456",
    email: "buyer@example.com",
  },
});

The handler sends order_completed, attaching the session UUID, shop ID, and custom-commerce marker automatically. It does not send a referral checkout event when there is no attribution session. Use these handlers instead of constructing the raw tracking payload with sendEvent().

3. Send confirmed orders from your backend

Send the order from your backend once your OMS has confirmed payment. Superfiliate matches this trusted order record with the browser event to connect the customer’s journey to a paid conversion. The authenticated request provides the order status and amounts; the browser event on its own is not enough to record the order for attribution.

Trigger this request from your backend after verifying your commerce platform’s order/payment notification. Build the payload from your stored order, and send it for every paid order, including orders without a creator code. Superfiliate does not automatically handle cancellations or refunds from your OMS, so do not submit an order as paid before payment is confirmed. Agree on how later cancellations and refunds will be reconciled before launch. Use your backend’s order data for payment status and totals.

curl -X POST "https://api.superfiliate.com/api/v1/orders" \
  -H "Authorization: Bearer $SF_CLIENT_ID:$SF_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "order-123",
  "status": "paid",
  "currency": "USD",
  "customer_email": "buyer@example.com",
  "subtotal_value": "90.00",
  "total_value": "100.00",
  "discount_code": "JOHN",
  "external_created_at": "2026-10-22T15:30:00Z",
  "line_items": [
    {
      "external_id": "line-1",
      "external_product_id": "product-1",
      "external_variant_id": "variant-1",
      "name": "Everyday T-shirt",
      "sku": "TSHIRT-BLACK-M",
      "quantity": 2,
      "gross_unit_price": "50.00",
      "discount_total": "10.00",
      "subtotal_price": "90.00"
    }
  ]
}'

A 200 response returns the saved order with a Superfiliate id and your external_id. Save both for troubleshooting. The response confirms persistence; conversion processing happens asynchronously and still depends on attribution and program eligibility. See the Alpha order reference.

• Retry network errors, 429s, and server errors through a durable backend queue, with backoff. Reuse the same external ID and complete order payload; repeated requests update that order rather than insert a new one. Do not generate a new ID on retry.
• Fix credentials for 401, scopes for 403, and the response’s validation errors for 422 before retrying. See Errors and Rate Limiting.
• A mapped creator discount code can attribute the order directly. For no-code link attribution, Superfiliate matches the browser checkout event by order ID and uses its session’s related access event. Browser snapshot amounts do not replace the authenticated order data.

4. Test attribution end to end

Use an agreed test store and test creator, with program rules that allow the test purchase. Dry-run requests validate API contracts with synthetic data; they do not prove that your DNS, browser session, checkout, and real order pipeline are connected.

1. 1

   Follow the real creator link

   Start in a fresh browser session and open the creator’s returned referral URL. Confirm HTTPS, the correct destination, and preserved tracking parameters. Accept tracking consent for the positive test.

2. 2

   Check the attribution cookie and store-entry event

   After the attributed landing page calls await superfiliateSdk.handlePageView(), open Chrome DevTools → Application → Storage → Cookies and select your store domain. Confirm sf_microsite_session exists, note its UUID value, and check that its Domain covers your storefront and checkout/confirmation subdomains.

   In Chrome’s Network tab, filter for /api/events. Browser events are sent by POST to your configured creator-link domain, for example https://partners.yourstore.com/api/events. The exact hostname is the shop.micrositeDomain value in your storefront configuration. Check for a successful 2xx response and inspect the request payload: the event_type should be external_access or main_store_access, and its uuid should match the cookie. Check the creator code when present.

   Developers → Attribution script should become active after an event arrives. This status confirms event activity; continue through a paid test order to verify attribution.

3. 3

   Complete a purchase without a discount code

   Navigate through product, cart, checkout, and confirmation pages. Confirm your OMS marks the order paid and that the original sf_microsite_session value is still readable on the page calling handleCheckoutCompleted(). Enable Preserve log in Chrome’s Network tab to follow redirects. At the same /api/events URL, inspect the POST with event_type: order_completed. Confirm a successful response, the same session uuid,commerce_platform: custom, and the correct order_external_id. A no-code purchase isolates link/session attribution.

4. 4

   Check the backend submission and conversion

   Confirm your backend submits the same order ID with paid status and receives 200. Check Superfiliate’s conversion reporting for the intended creator/program and the API-submitted amounts after processing. You can also use Search conversions with conversions.read. If missing, collect the referral URL, order IDs, event UUID, request/response, and timestamps for Superfiliate support; exclude credentials.

   curl "https://api.superfiliate.com/api/v1/conversions?code=JOHN&include_pending=true&page=1&items=25" \
     -H "Authorization: Bearer $SF_CLIENT_ID:$SF_CLIENT_SECRET"

5. 5

   Check code attribution and retries separately

   Place another order with JOHN applied and confirm the creator mapping. Resubmit its identical backend payload and refresh the thank-you page: verify one order and one conversion remain. In another fresh browser session, test an organic visit with no code and confirm it is not credited to JOHN.

Repeat the affected scenarios for mobile, returning visits, SPA navigation, your actual checkout hostname, and delayed/out-of-order browser and server delivery. With declined consent or blocked scripts, verify the authenticated order still arrives and that missing browser tracking does not create false link attribution.

Launch checklist

• Domain connected, real creator link verified, and redirect parameters preserved.
• Creators mapped to the intended program and existing codes checked in both systems.
• Store-entry and checkout handlers exercised across the real shopping journey.
• Authenticated paid orders delivered reliably, with matching browser/server order IDs.
• No-code and code-based test conversions checked for creator, amounts, and duplicates.
• Owners assigned for failed order deliveries and attribution issues.

Before choosing a launch date, agree on migration volume, historical data scope, refund/cancellation handling, supported currencies, and any subscription-renewal requirements with Superfiliate. The order contract shown here accepts pending/paid; it does not define a refund or cancellation workflow. Estimate implementation time after checking DNS access, checkout extensibility, and backend order notifications.

Optional next steps

• Sync discount codes to create and update discounts in your own commerce platform.
• Fulfill gifts with your OMS to automate gift orders and report placement and shipment.