Run Your Affiliate Program via API

Everything the Affiliate Hub dashboard does for inviting and tracking partners is also available over the API. This guide walks through the full lifecycle: inviting an affiliate, understanding how sales are attributed, and reading commission data back. If you are new to the affiliate platform itself (programs, commission terms, payouts), start with the Affiliate Program feature guide — this page assumes a program already exists on your store.

Prerequisites

An affiliate program on your store, created from the Affiliate Hub.
An API key with the right scopes: reading affiliate data requires affiliates:read, creating invitations requires affiliates:write. Keys created with Full access cover both, including scopes added after the key was created.

All endpoints work in both test and live mode — use your test-mode API key while integrating. Responses carry a mode field so you always know which environment you are looking at.

1. Invite partners programmatically

Create an invitation from your own backend — for example when someone fills in a “become a partner” form on your site, or when you sync partners from your CRM:

curl -X POST https://api.creem.io/v1/affiliates/invites \
  -H "x-api-key: creem_..." \
  -H "Content-Type: application/json" \
  -d '{"email": "partner@example.com", "name": "Jane Partner"}'

The invitee receives the same invitation email as a dashboard-created invite, and appears in your Affiliate Hub’s Invites tab immediately. Once they accept, an affiliate account is provisioned and they become an active partner. program_id is optional — when omitted, the invitation is created for your store’s affiliate program. Pass it explicitly if your store runs more than one program. A few behaviors to design around:

Behavior	Response
Same email invited twice	`409 Conflict` — one pending invitation per email
Invitee is a member of your store team	`400 Bad Request` — team members cannot be affiliates
Pending-invite limit reached	`400 Bad Request` — see below
Key lacks `affiliates:write`	`403 Forbidden`

A store can have at most 100 pending invitations at a time. Accepted invitations free their slot; you can also cancel stale pending invites from the Affiliate Hub. If you legitimately need a higher limit, contact support@creem.io and we will raise it for your store — no code changes needed.

Track the lifecycle of your invitations with List affiliate invites — each invitation carries a status of pending, accepted, canceled, or rejected.

2. How sales get attributed

A sale is credited to an affiliate through one of three paths. Each checkout gets exactly one attribution — they never stack, and an explicit affiliate_code on the API request takes precedence.

Referral link (cookie-based)

The default path. Each affiliate gets a unique referral link (creem.io/affiliate?code=...). A click records attribution and redirects the visitor to your site; any extra query parameters on the link (UTMs, deep-link params) are forwarded to your destination URL, so affiliates can target specific landing pages and you can see their campaigns in your own analytics.

Affiliate code on the Checkout API

For server-driven and headless checkouts where cookies never enter the picture. If you already know which affiliate referred the customer, pass their referral code when creating the checkout — no click required.

Affiliate-linked discount code

If an affiliate has a discount code assigned in the Affiliate Hub, any checkout using that code credits them — including codes prefilled via the API.

Passing the code at checkout creation:

curl -X POST https://api.creem.io/v1/checkouts \
  -H "x-api-key: creem_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_...",
    "affiliate_code": "AFFXXXXXXXX"
  }'

The affiliate_code value is the affiliate’s referral-link code — the same code you see in List affiliates responses and the affiliate sees in their portal. An invalid, inactive, or foreign-store code is rejected with 400 Bad Request before the checkout is created, so a typo can never silently drop attribution.

3. Commissions

Commission math follows the program’s configuration — you do not compute anything yourself:

Type and value: percentage of the sale or a fixed amount per sale.
Recurrence: recurring pays on every subscription payment; one_time pays only on the first payment of a subscription (the CPA model).
Duration: recurring commissions can be capped to a number of months.
Per-product rates: individual products can override the program rate, including a 0 rate to exclude a product entirely.

Read results back with List affiliate commissions, or aggregate views per partner via List affiliates (clicks, conversions, earnings per affiliate). Payouts to affiliates are handled by Creem through the affiliate portal, including identity verification — nothing to build on your side. See the feature guide for the payout flow.

Current limitations

No affiliate webhooks yet. Invitation acceptance and new conversions are not pushed as webhook events — poll List affiliate invites and List affiliate commissions where you need to react to changes.
Program management stays in the dashboard. Creating programs and editing commission terms is done in the Affiliate Hub, not the public API.

Endpoint reference

Endpoint	Scope	Purpose
`GET /v1/affiliates`	`affiliates:read`	List your affiliates with performance stats
`GET /v1/affiliates/:id`	`affiliates:read`	Retrieve one affiliate
`GET /v1/affiliates/:id/commissions`	`affiliates:read`	List an affiliate’s commissions
`POST /v1/affiliates/invites`	`affiliates:write`	Invite a partner by email
`GET /v1/affiliates/invites`	`affiliates:read`	List invitations and their status

​Prerequisites

​1. Invite partners programmatically

​2. How sales get attributed

Referral link (cookie-based)

Affiliate code on the Checkout API

Affiliate-linked discount code

​3. Commissions

​Current limitations

​Endpoint reference

Prerequisites

1. Invite partners programmatically

2. How sales get attributed

3. Commissions

Current limitations

Endpoint reference