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, write discounts (used only to mint affiliate discount codes), the web pixel pair, and write store credit (used only when a campaign rewards affiliates with store credit). These let Rekomi track conversions, reverse commissions on refunds and post store credit.

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.

What the app does for your store

Referral links. Every affiliate gets a link to your store with their code attached (and product links from your synced catalog). The app's web pixel records the click first-party, and Rekomi also reads the buyer journey Shopify stores on each order, so a sale is attributed even when the shopper blocked trackers or came back days later.

Discount codes. Each affiliate can get a personal code, created as a real Shopify discount from a coupon offer you define (percent or amount off, optionally scoped to products with Shopify's own picker). A redeemed code credits the affiliate even when no click was tracked, which is how most social and video traffic converts. Revoking the code deactivates the Shopify discount.

Orders. Shopify's orders/paid webhook is the sale: the commission mints the moment the order is paid, on the order total by default, or on the goods line when a per-product rate applies. Test orders are recorded only while your workspace is in test mode.

Per-product rates and assigned partners. Set a different rate on the products you want pushed (or zero on the ones you do not), and assign a product to specific affiliates so only they earn on it. See Product commissions.

Customers into affiliates. The Grow page lists your top customers by lifetime spend; invite them in one click and they get a link and a code.

Store credit instead of cash. A campaign can reward affiliates with Shopify store credit instead of a cash commission: the commission rate you set (or a fixed amount per sale) lands on the affiliate's store credit account and applies at their next checkout. Nobody needs a payout method or a tax form, and a refund takes the credit back. Store credit needs the write store credit permission; if your store installed the app before that permission existed, open the Rekomi app once and approve the updated permissions when Shopify asks. See Store credit rewards.

Payouts and tax. For cash commissions you fund a payout run (or turn on automatic payouts) and Rekomi pays each affiliate in 130+ countries, charges a flat 3% of the commissions paid on your Shopify invoice, collects the W-9 and W-8 forms and files the 1099-NECs as payer of record. See Payouts.

Refunds, cancellations and chargebacks

• Refunds. Shopify fires refunds/create on every refund and the app listens to it: a partial refund reverses its proportional share of the commission (before tax), a full refund reverses it all and marks the sale Refunded. Nothing to forward.
• A refund after the affiliate was paid. The refunded share of the paid commission is recovered from that affiliate's next payout automatically and shows under "Owed back from refunds" on your Payouts page, where you can also write it off; the paid line can still be reversed on Stripe from the payout's page if you want the money back right away. See Refunds after a payout.
• Cancellations. An order cancelled before payment never becomes a sale; a paid order you cancel is refunded by Shopify, and that refund reverses the commission.
• Chargebacks. A lost Shopify Payments dispute is not a refund event. Refund the order in Shopify (so refunds/create fires) or mark the sale invalid from the Sales page.
• Order edits. Adding items to a paid order does not change the commission already recorded; removing items is a refund in Shopify and reverses its share.
• The refund hold. Commissions become payable only after your refund-hold window (30 days by default), so most refunds land before any money moves.

Shopify Collabs

Shopify ships a native affiliate program called Collabs. Rekomi adds cross-platform affiliate identity (one affiliate working many brands), commission tiers, per-product rates, sub-affiliate recruiting, store credit rewards and the open creator network. The two can run side by side on the same store, and the importer under Settings, Import brings your Collabs affiliates and history across.

Developer fallback: Custom Pixel plus webhook to S2S

The rest of this page is for stores that prefer not to install an app. Everything above happens on its own with the app; the manual path tracks links and orders only.

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. Shopify's total_price is a major-unit decimal in the shop currency (order.currency), so the handler scales it to integer minor units of that currency before sending: whole yen for JPY, thousandths for KWD, cents for everything else (see Conversion currency).

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}`.
  //    total_price is a major-unit decimal in the shop currency; Rekomi wants integer
  //    minor units of order.currency (whole yen for JPY, thousandths for KWD).
  const ZERO_DEC = new Set(['BIF', 'CLP', 'DJF', 'GNF', 'ISK', 'JPY', 'KMF', 'KRW', 'PYG', 'RWF', 'UGX', 'VND', 'VUV', 'XAF', 'XOF', 'XPF']);
  const THREE_DEC = new Set(['BHD', 'JOD', 'KWD', 'OMR', 'TND']);
  const dec = ZERO_DEC.has(order.currency) ? 0 : THREE_DEC.has(order.currency) ? 3 : 2;
  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) * 10 ** dec), // integer minor units of order.currency
    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 (manual path)

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.

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 (manual path)

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. (With the app installed this needs no relay: the app subscribes to the refund webhook itself.)

Troubleshooting (manual path)

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

• Rekomi for online stores
• Store credit rewards
• Payouts
• S2S tracking API reference
• No-code and non-Stripe checkout tracking
• Shopify Custom Pixels docs