> ## Documentation Index
> Fetch the complete documentation index at: https://docs.creem.io/llms.txt
> Use this file to discover all available pages before exploring further.

# LinkJolt Affiliate Program Integration

> Connect LinkJolt affiliate tracking to your Creem store with one restricted API key. LinkJolt adds its own webhook, credits sales and renewals to affiliates, and creates affiliate discount codes in your store.

## Overview

[LinkJolt](https://www.linkjolt.io/integrations/creem-affiliate-tracking?utm_source=creem\&utm_medium=docs)
is affiliate tracking and management software with a Creem connection. An affiliate shares a link or
a discount code, LinkJolt records the click, and when that visitor buys through your Creem checkout,
the sale arrives on a signed webhook and is credited to the affiliate.

You connect with one API key. LinkJolt uses it to add its own webhook to your Creem store and read
the signing secret, so you don't copy a URL or paste a secret. Sales, subscription renewals, trials,
refunds and chargebacks all arrive through that webhook. LinkJolt also uses the key to create a
Creem discount code for each affiliate.

<Card title="What you'll need" icon="gears">
  * A Creem account (production or Test Mode, LinkJolt follows the key you connect with)
  * A LinkJolt account
    ([sign up](https://www.linkjolt.io/auth/sign-up?utm_source=creem\&utm_medium=docs))
  * A Creem API key with the `webhooks:read`, `webhooks:write`, `discounts:read`, `discounts:write`
    and `products:read` scopes
</Card>

## How It Works

Creem hosts checkout on its own domain, so the affiliate referral needs a way to travel from your
site into the sale. It travels as one metadata field, `linkjolt_ref`, and on Creem payment links the
LinkJolt tracking script adds it for you.

* A visitor clicks an affiliate's link and lands on your site. The LinkJolt tracking script stores
  the referral in their browser for 30 days and exposes it as `window.linkjolt.referral`.
* They go to checkout with the referral attached as `linkjolt_ref` metadata. The script adds it to
  every Creem payment link and product link on your page. If your server creates the checkout, you
  add it there.
* Creem processes the payment and sends a signed webhook to LinkJolt.
* LinkJolt matches the referral, or the discount code used at checkout, to the affiliate,
  calculates the commission, and records it as pending until you approve it.

Sales never come through the API. They arrive on the signed webhook, and the API key only manages
the webhook and the discount codes.

<Note>
  LinkJolt reads `linkjolt_ref` from checkout metadata. Creem's [built-in affiliate
  feature](/features/affiliate-program) uses its own `creem_ref` URL token, which never ends up in
  your metadata, so you can run both side by side.
</Note>

## Integration Steps

You connect Creem's Test Mode first, check a purchase end to end, then connect your live store.

<Steps>
  <Step title="Create a campaign in LinkJolt">
    In LinkJolt, create a campaign. It holds your commission terms:

    * **Commission**: a percentage of each sale, or a fixed amount.
    * **Renewals**: whether subscription renewals pay commission too, and for how many months or
      payments.
    * **Approval**: whether affiliates who apply are approved automatically, or wait for you.

    Then invite affiliates from LinkJolt, or share your program's join page so they can apply.
  </Step>

  <Step title="Create a restricted API key in Creem">
    In your Creem dashboard, switch on **Test Mode**, go to **Developers > API Keys** and create a key.
    Switch **Full access** off and grant only the scopes LinkJolt uses:

    | Scope | Used for |
    | - | - |
    | `webhooks:read` and `webhooks:write` | Adding the LinkJolt webhook to your store and reading its signing secret |
    | `discounts:read` and `discounts:write` | Creating a discount code for each affiliate |
    | `products:read` | Listing your active products, so each new code applies to them |

    With these scopes the key can't change your products, customers or orders.

    A Test Mode key starts with `creem_test_`. LinkJolt records sales from Test Mode as test sales and
    never pays them out. You create the live key the same way in the last step.
  </Step>

  <Step title="Connect Creem in LinkJolt">
    In LinkJolt, open **Integrations** and choose the **Creem** tab. Paste the key into **Creem API
    key** and click **Set it up**. LinkJolt then:

    * adds a webhook named **LinkJolt** to your Creem store, subscribed to every event
    * reads the webhook back from Creem to confirm it was saved
    * reads the webhook's signing secret
    * stores the key encrypted, to create discount codes and to check the webhook once a day

    The new webhook is in Creem under **Developers > Webhooks**. Leave its events as they are.

    <Tip>
      If you'd rather not give LinkJolt an API key, choose **Set it up by hand instead** on the Creem
      tab. Add the webhook in Creem yourself with every event selected, and paste its signing secret
      into LinkJolt. Tracking works the same, but LinkJolt can't create discount codes or run the daily
      check.
    </Tip>
  </Step>

  <Step title="Add the LinkJolt tracking script to your site">
    The Creem tab asks how your customers pay: payment links on your site, a checkout your own code
    creates, or discount codes only. For the first two, add the tracking script to the `<head>` of your
    marketing site. It records affiliate clicks and stores the referral for the next step.

    ```html Tracking script theme={null}
    <script src="https://www.linkjolt.io/api/tracking.js?id=YOUR_MERCHANT_ID"></script>
    ```

    The Creem tab shows the script with your ID filled in, plus a version for React. If you only use
    discount codes, there's nothing to install, so skip to the last step.
  </Step>

  <Step title="Pass the referral into checkout">
    This step connects a click to a sale. Without it, sales arrive with no referral and no affiliate is
    credited.

    **Payment links**: nothing to add. The tracking script appends `metadata[linkjolt_ref]` to every
    link on the page that points at a Creem payment link or product page (`creem.io/payment/`,
    `creem.io/product/` and their `/test/` forms), including links added after the page loads. Creem
    copies the parameter into the checkout's metadata.

    **Checkout API or SDK**: read the referral in the browser with `window.linkjolt.referral`, send it
    with your checkout request, and set it as `metadata.linkjolt_ref` where your server creates the
    checkout.

    <CodeGroup>
      ```json Checkout API theme={null}
      {
        "product_id": "prod_your_product",
        "success_url": "https://yoursite.com/success",
        "metadata": { "linkjolt_ref": "REFERRAL_FROM_YOUR_FRONTEND" }
      }
      ```

      ```ts TypeScript SDK theme={null}
      const checkout = await creem.checkouts.create({
        productId: "prod_your_product",
        successUrl: "https://yoursite.com/success",
        metadata: { linkjolt_ref: referral }, // the value of window.linkjolt.referral
      });
      // send the customer to checkout.checkoutUrl
      ```

      ```js Links you build in JavaScript theme={null}
      const url = new URL("https://www.creem.io/payment/prod_your_product");
      const referral = window.linkjolt?.referral;
      if (referral) url.searchParams.set("metadata[linkjolt_ref]", referral);
      window.location.href = url.toString();
      ```
    </CodeGroup>

    **Links you build in JavaScript**: the script rewrites links on the page, not a URL your code opens
    (for example with `window.open` or `location.href`). Add the parameter yourself, as in the third
    tab.

    <Tip>
      Creem copies checkout metadata onto the subscription, and every `subscription.paid` event carries
      it. Renewals keep crediting the same affiliate without anything extra.
    </Tip>
  </Step>

  <Step title="Verify with a test purchase, then go live">
    Run this once in Test Mode before you rely on it.

    1. **Visit your site through an affiliate link.** Take any affiliate's link from LinkJolt, or a test
       affiliate's, and open your site with it.
    2. **Check the link carries the referral.** Hover a Creem payment link on the page. Its address now
       includes `linkjolt_ref`. If you use the Checkout API, log the value you send instead.
    3. **Buy with a test card.** Complete the checkout with card `4111 1111 1111 1111`, any future
       expiry and any CVC ([test cards](/getting-started/test-mode)). In LinkJolt, the sale appears under
       **Test sales** on the **Commissions** page, credited to that affiliate.
    4. **Refund the purchase in Creem.** LinkJolt reverses the commission.
    5. **Resend the webhook.** In Creem, resend the `checkout.completed` delivery. LinkJolt keys every
       payment by its Creem transaction, so it still shows one sale and one commission.

    To go live, switch Test Mode off in Creem, create a live API key with the same scopes, and paste it
    into the same field on LinkJolt's Creem tab. LinkJolt adds its webhook to your live store. Your Test
    Mode connection stays, and test sales stay separate from your live commissions.
  </Step>
</Steps>

## Affiliate discount codes

A discount code credits an affiliate without a link, for affiliates who promote by voice or video.
Once your live store is connected with an API key:

* **One code at a time**: on the **Coupons** tab of LinkJolt's **Campaigns** page, create a coupon,
  pick the affiliate, choose **Creem discount**, and enter the code and the discount. LinkJolt
  creates it as a discount in your Creem store, with the percentage or amount and the duration you
  chose.
* **A code for every affiliate**: switch on **A coupon code for every affiliate** in a campaign's
  settings, and every approved affiliate gets their own code, named after them.

A sale that uses the code is credited to that affiliate. LinkJolt creates each code for the products
active in your store at that moment, so a product you add later needs new codes.

Discounts you create in Creem yourself work too. Register each one on the same Coupons tab by its
`dis_` ID.

## What Gets Tracked

| Event | What happens |
| - | - |
| One-time sale | Commission recorded from `checkout.completed`, pending until you approve it |
| First subscription payment | Recorded once, whether `checkout.completed` or `subscription.paid` arrives first |
| Subscription renewal | Commission from each `subscription.paid`, at your recurring rate, up to the cap you set |
| Trial start | Recorded as a trial, with no commission until the first real payment |
| Refund | Commission reduced in proportion for a partial refund, removed for a full one |
| Chargeback | Commission reversed in full |
| Discount code | A sale using an affiliate's code credits them, even without a link |
| Test Mode purchase | Recorded as a test sale, separate from your live commissions, and never paid out |

Commission is calculated on what the customer paid, or on the price before tax if you switch on
**Commission on the price before tax** in LinkJolt's settings. Every payment is keyed by its Creem
transaction, so webhook retries and manual resends don't count twice.

## Refunds and chargebacks

Creem's `refund.created` event carries `refund_amount`, the amount of that refund. LinkJolt reverses
the commission in proportion to what has been refunded, and a full refund or a chargeback removes it.
A redelivered or out-of-order event doesn't reverse anything twice, and a payout still queued for the
sale is reduced or cancelled to match.

Every commission stays pending until you approve it, so a refund that arrives first adjusts it before
anything is paid. If you've already paid the commission, LinkJolt records the refund but doesn't take
money back from the affiliate. Settle that with them directly.

## Good to Know

* **The daily check.** Once a day LinkJolt reads its webhook with your key. If the webhook was
  switched off, changed or deleted, or the key revoked, the Creem tab says what's wrong and LinkJolt
  emails you once. LinkJolt never changes the webhook by itself: if you switched it off, it stays
  off until you click **Turn it back on** on the Creem tab.
* **Short links and storefronts.** The script adds the referral to full payment links and product
  links on your own site. It can't reach a Creem short link (`l.creem.io`) or a
  [storefront](/features/storefronts) page, so link to the payment link itself where affiliates send
  traffic, or give those affiliates a discount code.
* **Custom domains.** With a [custom domain](/features/custom-domains), new payment links point at
  your subdomain (for example `pay.yourbrand.com`) instead of `creem.io`. Add
  `&creem_domain=pay.yourbrand.com` to the tracking script's URL and the script adds the referral to
  links on that domain too. If you connected with an API key, LinkJolt finds the domain in your
  products and the Creem tab shows the script with it filled in.
* **One Creem store per LinkJolt brand.** LinkJolt refuses a store that's already connected to
  another brand until you disconnect it there.
* **Disconnecting.** Click **Disconnect Creem** on the Creem tab. LinkJolt removes its webhook from
  your store and keeps the discount codes it created, since they live in Creem.

<Card title="LinkJolt for Creem" icon="book-open" href="https://www.linkjolt.io/integrations/creem-affiliate-tracking?utm_source=creem&utm_medium=docs">
  LinkJolt's own page for the Creem integration.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.