Affiliate Promo Codes API

Create, edit and sync Stripe promo codes attached to affiliate partners.

Promo codes are real Stripe coupons plus promotion codes on the organization's connected account. Growth mirrors them so redemptions can be attributed to a partner.

GET /api/v1/affiliate/promo-codes

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

{
  "promoCodes": [
    {
      "id": "p31...",
      "code": "MARIE20",
      "status": "active",
      "discountType": "percent",
      "percentOffBps": 2000,
      "currency": "eur",
      "duration": "forever",
      "redemptionsCount": 14,
      "maxRedemptions": 100,
      "expiresAt": null,
      "affiliate": { "id": "n97...", "name": "Marie Dupont" },
      "stripePromotionCodeId": "promo_..."
    }
  ],
  "sampleLimited": false
}

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

POST /api/v1/affiliate/promo-codes

Field	Type	Description
`code`	`string`	Required customer-facing code.
`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.
`affiliateId`	`string`	Links redemptions to that partner.
`duration`	`string`	`forever` (default), `once` or `repeating`.
`durationInMonths`	`number`	1-36, required when `duration` is `repeating`.
`startsAt` / `expiresAt`	`number`	Timestamps in ms; the end date must be in the future.
`maxRedemptions`	`number`	Total redemption limit.

curl -X POST -H "x-api-key: org_api_key" -H "Content-Type: application/json" \
  -d '{"code":"MARIE20","discountType":"percent","percentOffBps":2000,"affiliateId":"n97..."}' \
  "https://growth.example.com/api/v1/affiliate/promo-codes"

PATCH /api/v1/affiliate/promo-codes/:promoCodeId

Field	Type	Description
`status`	`string`	`active` or `paused`.
`expiresAt`	`number \| null`	New deadline, or `null` to clear it.
`maxRedemptions`	`number \| null`	New limit, or `null` to clear it.

Stripe promotion codes are immutable except for active: changing the deadline or the limit archives the Stripe code and recreates one on the same coupon with the same customer-facing string. Growth carries the redemptions over, so lifetime totals stay correct.

Sync codes created in Stripe

POST /api/v1/affiliate/promo-codes/sync

Body: { "limit": 100, "startingAfter": "promo_..." } (both optional). Imports promotion codes created directly in the Stripe dashboard and returns processed, created, updated, skipped, linked, unassigned, hasMore and nextCursor.

Error responses:

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

Notes

Creating a code requires a connected Stripe account with charges enabled.
A code that already exists in Stripe must be imported with sync before Growth will create it.
Codes can exist without a partner and be linked later.

Affiliate Promo Codes API

List promo codes

Create a promo code

Update a promo code

Sync codes created in Stripe

Notes