Install on Shopify

The fastest, most reliable way to add Rekomi to Shopify is the native Rekomi app from the Shopify App Store. Install it, approve the requested scopes, pick a campaign, and give each affiliate a unique Shopify discount code. Orders placed with an affiliate's code are attributed automatically, and refunds reverse the commission. No theme edits, no Custom Pixel to maintain, and no relay to build.

If you would rather wire the integration up yourself (or you are on a setup where the app is not available yet), the manual Custom Pixel plus webhook-to-S2S path still works and is documented below as a fallback.

Native: install the Rekomi app (recommended)

Step 1. In your Shopify admin go to Apps > Shop the App Store, search for Rekomi, and click Install.

Step 2. Approve the requested scopes (read orders, read products, read customers, and write discounts) so Rekomi can mint each affiliate's unique discount code, record conversions, and reverse commissions on refunds.

Step 3. Rekomi opens inside your Shopify admin and connects your store automatically. A campaign is created for you, and the app starts listening for orders immediately. Attribution is discount-code first: each affiliate gets a unique Shopify discount code, and any paid order that uses it (or, as a fallback, an order from a customer that affiliate previously referred) is attributed and read server-side through Shopify's order webhook. There is nothing to paste into your theme.

Manage everything inside Shopify

After install, the full Rekomi admin runs embedded in your Shopify admin, so you never leave Shopify to run your program:

• Overview with clicks, conversions, commission, conversion rate, active affiliates, and pending payouts, plus a performance trend and recent activity.
• Affiliates: approve or reject applicants and invite new partners.
• Campaigns and Conversions: see each campaign's performance and the sales attributed to your affiliates.
• Payouts: pay affiliates with one click and review payout history.
• Coupons: see your coupon offers, the codes minted from them, and redemptions.
• Plan & billing: manage your subscription, billed through Shopify.
• Settings: set your minimum payout and reporting currency.

Authentication uses Shopify session tokens (App Bridge), so no separate Rekomi login is needed inside the admin.

Most Shopify affiliate apps charge a percentage of your referral sales. Rekomi charges 3% of the commissions you actually pay out, not on sales, and runs the payouts and taxes for you.

To verify the native install: create a campaign, generate an affiliate's discount code from the Coupons tab, then place a normal order using that code. The conversion appears on the Conversions tab within a minute. (Shopify test orders are intentionally ignored, so use a real order to verify.)

Fallback: manual Custom Pixel plus webhook to S2S

Two Shopify architectural details shape the manual install. 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 supported manual paths are a self-contained Custom Pixel (faster to set up) or a webhook-to-S2S relay (more reliable for production).

Path A: Custom Pixel (fastest manual setup)

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 (full snippet available from your in-app install hub at /dashboard/setup/install/platforms/shopify).

Step 3. Click Save, then Connect.

The Custom Pixel runs across the storefront, checkout, and thank-you page. It handles two events:

• page_viewed: parses the URL for ?via= (and the other 15 attribution params), POSTs the click to /api/v1/r/c
• checkout_completed: reads order data (id, total, currency, email) from the analytics payload, POSTs the conversion to /api/v1/r/convert

No additional pixel install elsewhere on the theme. The Custom Pixel is fully self-contained.

Path B: webhook + S2S relay (most reliable manual setup)

If you need higher reliability than the sandboxed Custom Pixel (e.g., when buyers have analytics blockers active), 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 affiliate slug from note_attributes (set by your storefront snippet).
  const noteAttrs = order.note_attributes || [];
  const referralAttr = noteAttrs.find(a => a.name === 'rekomi_affiliate_slug');
  if (!referralAttr) return res.sendStatus(200); // No affiliate involved.

  // 4. Relay to Rekomi.
  const body = JSON.stringify({
    external_event_id: order.id.toString(),
    affiliate_slug: referralAttr.value,
    amount_cents: Math.round(parseFloat(order.total_price) * 100),
    currency: order.currency,
    customer_email: order.email,
  });
  const sig = crypto.createHmac('sha256', process.env.REKOMI_S2S_SECRET).update(body).digest('hex');
  await fetch('https://api.rekomi.com/api/tracking/s2s', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-Rekomi-Signature': sig },
    body,
  });
  res.sendStatus(200);
});

The note_attributes array is where the storefront should write the affiliate slug at order creation. Add a storefront snippet (Theme > Edit code > sections/header.liquid or similar) that calls Cart API's attributes to persist the slug from window.Rekomi.getReferral() into the order.

Test the install

Place a test order with ?via=test appended to a storefront URL. The conversion should appear on the campaign's Activity tab within a minute. If only a click registers (no conversion), the Custom Pixel fired but checkout_completed did not pick up the affiliate context, either because the via parameter was not preserved into the checkout, or the webhook path is misconfigured.

Quirks worth knowing

Custom Pixels are sandboxed. External <script> tags cannot load inside a Custom Pixel; everything has to be inlined. That is why Path A uses a self-contained pixel rather than a script loader.

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.

Liquid templating is rich. Unlike Webflow's static order page, Shopify exposes {{ order.total_price }}, {{ customer.email }}, and similar tokens. The Custom Pixel path uses the analytics event payload (cleaner); the webhook path reads from the order JSON directly.

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 external_event_id from 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. The Custom Pixel's checkout_completed and the S2S webhook both fired for the same order. Rekomi de-dupes on external_event_id, 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
• JavaScript pixel reference
• Shopify Custom Pixels docs