Install on Shopify

The Rekomi Affiliate Marketing app is live on the Shopify App Store. Installing it is the recommended path: it is no-code, and it tracks everything the manual path below tracks plus more. Affiliate links track out of the box (the app installs its web pixel automatically and also reads the buyer journey Shopify itself records on each order, so link attribution works even when the buyer blocks trackers), orders are attributed automatically through the app's order webhook, refunds reverse the commission, and each affiliate can get a unique Shopify discount code, no theme edits and no relay to build.

Install the Rekomi app (recommended)

Step 1: install from the App Store. Open Rekomi Affiliate Marketing on the Shopify App Store and click Install. Approve the requested permissions: read orders, read products, read customers, and write discounts (used only to mint affiliate discount codes). These let Rekomi track conversions and reverse commissions on refunds.

Step 2: pick a plan. The app opens on its Subscription page. Choose a plan and approve the charge on Shopify's billing screen; every plan starts with a 14-day free trial, and your subscription is billed through Shopify alongside your other apps.

Step 3: create your campaign. The setup guide walks you through creating a campaign with the commission you want to pay and linking your store to it. Rekomi starts listening for orders right away.

Step 4: verify. Place a test order with ?via=test appended to a storefront URL and confirm the conversion appears on the campaign's Performance tab within a minute.

From there the whole program runs from the Rekomi app inside the Shopify admin: campaigns and the signup-page designer, the product catalog with per-product rates, coupon offers scoped with Shopify's own product picker, affiliates and their product links, referred sales that link straight to the order in your admin, banner uploads for promo assets, one-click invites for your top customers, the 21-source importer under Settings, Import, payouts (one-click or on an automatic schedule), and plan billing.

The manual install (Custom Pixel plus webhook to S2S)

If you prefer not to install the app, the manual self-serve path is a Custom Pixel for click capture plus an order webhook relayed to Rekomi's S2S endpoint. Two Shopify architectural details shape it. First, Shopify Payments is Stripe under the hood, but Shopify owns the Stripe account, not you, so you have no merchant Stripe webhook to subscribe Rekomi to. Second, Custom Pixels run in a sandboxed runtime where external <script> tags cannot load, so the standard "paste this script in your head" approach does not work either. The install is therefore two halves: a Custom Pixel captures the affiliate click (Part 1), and an order webhook relayed to Rekomi's S2S endpoint records the conversion server-side (Part 2). Install both.

Part 1: Custom Pixel (click capture)

Step 1. In Shopify admin: Settings > Customer events > Add custom pixel.

Step 2. Name it Rekomi. Set Permission to Not required. Paste the Custom Pixel code (grab the full snippet from your Rekomi dashboard under Setup, Install tracking script, and choose Shopify).

Step 3. Click Save, then Connect.

The Custom Pixel runs across the storefront and checkout. It handles click capture only:

• page_viewed: parses the landing URL for ?via=, POSTs the click (the affiliate slug plus your program id) to /api/v1/r/c, and stashes the slug so it rides along to the order.

The Custom Pixel does not record the sale. There is no browser conversion call: the old browser-pixel convert() sale path was removed, and the conversion is recorded server-side in Part 2, where Shopify's order webhook delivers full order data without the sandbox restrictions.

Part 2: order webhook to S2S (conversion fire)

This is where the conversion is recorded. Wire up a server-side relay from Shopify's Order webhook.

Step 1. Shopify admin > Settings > Notifications > Webhooks > Create webhook.

• Event: Order payment
• URL: https://your-app.example.com/rekomi-shopify-webhook?secret=YOUR_SHARED_SECRET
• Format: JSON
• API version: latest stable

Step 2. Build the relay handler. Shopify signs every webhook with the secret you set during webhook creation (HMAC-SHA256 in the X-Shopify-Hmac-Sha256 header). Validate the signature, then forward to Rekomi's S2S endpoint with HMAC.

const crypto = require('crypto');

app.post('/rekomi-shopify-webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  // 1. Validate Shopify HMAC
  const shopifyHmac = req.get('X-Shopify-Hmac-Sha256');
  const computed = crypto
    .createHmac('sha256', process.env.SHOPIFY_WEBHOOK_SECRET)
    .update(req.body)
    .digest('base64');
  if (computed !== shopifyHmac) return res.sendStatus(401);

  // 2. Validate URL shared secret too (defense in depth)
  if (req.query.secret !== process.env.SHARED_SECRET) return res.sendStatus(401);

  const order = JSON.parse(req.body.toString());

  // 3. Pull the affiliate slug from note_attributes (set by your storefront snippet).
  //    The attribute name is rekomi_via, the same name the Rekomi pixel snippet uses.
  const noteAttrs = order.note_attributes || [];
  const referralAttr = noteAttrs.find(a => a.name === 'rekomi_via');
  if (!referralAttr) return res.sendStatus(200); // No affiliate involved.

  // 4. Relay to Rekomi. Field names are camelCase; the signature is
  //    t={unix},sig={hex} where hex = HMAC-SHA256 of `${ts}.${body}`.
  const ts = Math.floor(Date.now() / 1000);
  const body = JSON.stringify({
    externalEventId: order.id.toString(),
    affiliateSlug: referralAttr.value,
    amountCents: Math.round(parseFloat(order.total_price) * 100),
    currency: order.currency,
    customerEmail: order.email,
  });
  const sig = crypto
    .createHmac('sha256', process.env.REKOMI_SIGNING_SECRET)
    .update(`${ts}.${body}`)
    .digest('hex');
  await fetch('https://api.rekomi.com/api/tracking/s2s', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.REKOMI_API_KEY}`,
      'X-Rekomi-Signature': `t=${ts},sig=${sig}`,
    },
    body,
  });
  res.sendStatus(200);
});

The note_attributes array is where the storefront should write the affiliate slug at order creation, under the attribute name rekomi_via (the same name the Rekomi pixel snippet uses). The pixel sandbox cannot expose window.Rekomi, so this half runs in your theme instead: add the standard Rekomi tracking script to your theme's head (theme code, unlike pixels, can load external scripts), then add a storefront snippet (Theme > Edit code > sections/header.liquid or similar) that calls the Cart API's attributes to persist window.Rekomi.getReferral() into the order as rekomi_via before checkout.

Test the install

Place a real order with ?via=test appended to a storefront URL. The conversion should appear on the campaign's Performance tab within a minute. If only a click registers (no conversion), Part 1 captured the click but Part 2 did not record the sale, either because the affiliate slug was not persisted into the order's note_attributes, or the order webhook did not reach your relay. Check your relay logs and confirm the storefront wrote the slug into the cart attributes. Shopify fires the order webhook for test orders too; if you do not want test data recorded, skip orders with test: true in your relay.

Quirks worth knowing

Custom Pixels are sandboxed. External <script> tags cannot load inside a Custom Pixel; everything has to be inlined. That is why Part 1 inlines the click-capture code rather than loading the standard head script.

Shopify Payments is not your Stripe account. Even though Shopify processes payments through Stripe internally, you cannot subscribe Rekomi to Shopify's Stripe webhooks. The Custom Pixel and S2S webhook paths are the two supported ways to attribute conversions on Shopify.

Shopify Collabs is a different feature. Shopify ships a native affiliate program called Collabs. Rekomi adds cross-platform affiliate identity, commission tiers, sub-affiliate recruiting, and the open creator network (launching soon). The two can run side by side on the same store.

The order webhook carries full order data. The conversion fire reads total_price, currency, email, and the affiliate slug straight from the order JSON Shopify delivers to your relay, with no sandbox restrictions and nothing to parse out of the rendered page.

Refunds

Shopify fires the refunds/create webhook on every refund. Subscribe to it and forward to Rekomi's /api/tracking/refund endpoint with the same externalEventId you sent for the original order. Commission reverses automatically.

Troubleshooting

Custom Pixel saves but no clicks appear in Rekomi. Verify the Custom Pixel was set to Connected (not just Saved). Check the Customer events panel for the pixel's status badge.

Conversion fires twice. Your order webhook relay delivered the same order to the S2S endpoint more than once (Shopify retries on non-2xx responses). Rekomi de-dupes on externalEventId, so the second fire is a silent no-op. Not a bug.

Affiliate slug not in note_attributes. Your storefront snippet did not persist the slug into the cart attributes before checkout. Verify the storefront has the snippet, then test with browser DevTools open to confirm the Cart API attribute call fires.

Related

• S2S tracking API reference
• No-code and non-Stripe checkout tracking
• Shopify Custom Pixels docs