Affiliate Offers API

Give each partner one promotional offer and mint as many code names on it as they need.

An offer is a partner's discount, held as one Stripe coupon. Every customer-facing code that partner hands out is a Stripe promotion code on that single coupon.

This split is what lets a partner run SUMMER20, PODCAST20 and NEWSLETTER20 side by side without the organization re-deciding the discount each time — and it means a discount that reaches an invoice as a bare coupon, with no promotion code, still resolves to the right partner.

List offers

GET /api/v1/affiliate/offers

Parameter	Type	Description
`affiliateId`	`string`	Only the offer of this partner.
`limit`	`number`	Rows to return, 1-200 (default 100).

{
  "offers": [
    {
      "id": "k71...",
      "name": "Launch offer",
      "discountType": "percent",
      "percentOffBps": 2000,
      "currency": "eur",
      "duration": "forever",
      "stripeCouponId": "XV4cYgfl",
      "previousStripeCouponIds": [],
      "affiliate": { "id": "n97...", "name": "Marie Dupont", "code": "marie" },
      "codesCount": 3,
      "redemptionsCount": 41,
      "codes": [
        { "id": "p31...", "code": "MARIE20", "status": "active", "redemptionsCount": 14 }
      ]
    }
  ],
  "sampleLimited": false
}

percentOffBps is hundredths of a percent (2000 = 20%). amountOff is in minor units.

Create or retune an offer

POST /api/v1/affiliate/offers

Field	Type	Description
`affiliateId`	`string`	Required. One offer per partner: posting again updates the existing one.
`discountType`	`string`	Required `percent` or `fixed`.
`percentOffBps`	`number`	Required for `percent`, 1-10000.
`amountOff`	`number`	Required for `fixed`, minor units.
`currency`	`string`	ISO currency. Defaults to the connected account's currency.
`name`	`string`	Internal label, also used to name the Stripe coupon.
`initialCode`	`string`	First customer-facing name to mint on the new offer. Ignored when the offer already exists.
`duration`	`string`	`forever` (default), `once` or `repeating`.
`durationInMonths`	`number`	1-36, required when `duration` is `repeating`.

curl -X POST -H "x-api-key: org_api_key" -H "Content-Type: application/json" \
  -d '{"affiliateId":"n97...","discountType":"percent","percentOffBps":2000,
       "duration":"repeating","durationInMonths":12,
       "name":"GREGOIRE","initialCode":"GREGOIRE"}' \
  "https://growth.example.com/api/v1/affiliate/offers"

The offer is saved before the first name is minted, so a name Stripe refuses comes back as initialCodeError on an otherwise successful response rather than failing the whole call.

Stripe coupons are immutable apart from their name. Changing the discount therefore creates a new coupon: the code names already handed out keep the terms they were created with, and only the next ones use the new discount. The replaced coupon is kept in previousStripeCouponIds so its redemptions still attribute.

Add a code name

POST /api/v1/affiliate/offers/codes

Field	Type	Description
`offerId`	`string`	Required offer to mint the name on.
`code`	`string`	Required customer-facing code.
`expiresAt`	`number`	Timestamp in ms; must be in the future.
`maxRedemptions`	`number`	Total redemption limit for this name.

The discount is not an input: it belongs to the offer. An offer carries as many names as the partner needs; lists show the newest 100.

curl -X POST -H "x-api-key: org_api_key" -H "Content-Type: application/json" \
  -d '{"offerId":"k71...","code":"PODCAST20"}' \
  "https://growth.example.com/api/v1/affiliate/offers/codes"

Names created this way appear in the Promo Codes API as well, and are edited, paused, archived and deleted through it. Deleting one never removes the offer's coupon.

Error responses:

Status	Meaning
`400`	Missing/invalid fields, code already in use, offer limit reached, or Stripe not connected.
`401`	Missing or invalid API key.
`404`	Unknown offer or partner.

Notes

Creating an offer requires a connected Stripe account with charges enabled.
Partners can add their own code names from their portal unless the program sets partnerCodeCreation to disabled.
A promotion code created straight in the Stripe dashboard on an offer's coupon is adopted by that offer on the next sync, partner included.