Promo Codes

Manage promotional codes for your Stripe integration. Promo codes are customer-facing codes that apply coupons to subscriptions or checkout sessions.

Endpoints

GET /api/admin/stripe/promo-codes

List all promo codes from your Stripe account.

Query Parameters

Parameter	Type	Description
`limit`	number	Maximum number of promo codes to return (default: 10, max: 100)
`starting_after`	string	Cursor for pagination
`coupon`	string	Filter by coupon ID

Response

{
  "data": [
    {
      "id": "promo_1234567890",
      "object": "promotion_code",
      "code": "WELCOME2024",
      "coupon": {
        "id": "coupon_1234567890",
        "object": "coupon",
        "name": "Welcome Discount",
        "percent_off": 20,
        "duration": "once"
      },
      "active": true,
      "customer": null,
      "expires_at": null,
      "max_redemptions": 100,
      "times_redeemed": 15,
      "restrictions": {
        "first_time_transaction": false,
        "minimum_amount": null,
        "minimum_amount_currency": null
      },
      "created": 1234567890
    }
  ],
  "has_more": false
}

POST /api/admin/stripe/promo-codes

Create a new promotional code.

Request Body

{
  "code": "BLACKFRIDAY2024",
  "coupon": "coupon_1234567890",
  "active": true,
  "max_redemptions": 500,
  "expires_at": 1732982400,
  "restrictions": {
    "first_time_transaction": true,
    "minimum_amount": 5000,
    "minimum_amount_currency": "usd"
  }
}

Parameters

Parameter	Type	Required	Description
`code`	string	Yes	The customer-facing promo code (case-insensitive)
`coupon`	string	Yes	The coupon ID to associate with this promo code
`active`	boolean	No	Whether the promo code is active (default: true)
`max_redemptions`	number	No	Maximum number of times the code can be redeemed
`expires_at`	timestamp	No	Unix timestamp when the promo code expires
`restrictions`	object	No	Restrictions on the promo code usage

Restrictions Object

Parameter	Type	Description
`first_time_transaction`	boolean	Limit to first-time customers only
`minimum_amount`	number	Minimum order amount in cents
`minimum_amount_currency`	string	Currency for minimum amount (e.g., "usd")

Response

{
  "id": "promo_1234567890",
  "object": "promotion_code",
  "code": "BLACKFRIDAY2024",
  "coupon": {
    "id": "coupon_1234567890",
    "object": "coupon",
    "name": "Black Friday Discount",
    "percent_off": 30,
    "duration": "once"
  },
  "active": true,
  "customer": null,
  "expires_at": 1732982400,
  "max_redemptions": 500,
  "times_redeemed": 0,
  "restrictions": {
    "first_time_transaction": true,
    "minimum_amount": 5000,
    "minimum_amount_currency": "usd"
  },
  "created": 1234567890
}

PATCH /api/admin/stripe/promo-codes

Update an existing promo code. Note: Only active can be updated after creation.

Request Body

{
  "id": "promo_1234567890",
  "active": false
}

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The promo code ID to update
`active`	boolean	Yes	Active status

Response

{
  "id": "promo_1234567890",
  "object": "promotion_code",
  "code": "BLACKFRIDAY2024",
  "coupon": {
    "id": "coupon_1234567890",
    "object": "coupon",
    "name": "Black Friday Discount",
    "percent_off": 30,
    "duration": "once"
  },
  "active": false,
  "customer": null,
  "expires_at": 1732982400,
  "max_redemptions": 500,
  "times_redeemed": 150,
  "restrictions": {
    "first_time_transaction": true,
    "minimum_amount": 5000,
    "minimum_amount_currency": "usd"
  },
  "created": 1234567890
}

Understanding the difference:

Feature	Coupon	Promo Code
Purpose	Defines the discount amount and duration	Customer-facing code that applies a coupon
Customer Facing	No	Yes
Multiple Codes	One coupon, one code	One coupon, many promo codes
Restrictions	None	Can have usage restrictions

Example Usage

curl -X POST /api/admin/stripe/promo-codes \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME2024",
    "coupon": "coupon_1234567890"
  }'

curl -X POST /api/admin/stripe/promo-codes \
  -H "Content-Type: application/json" \
  -d '{
    "code": "FLASHSALE",
    "coupon": "coupon_1234567890",
    "max_redemptions": 100,
    "expires_at": 1704067200
  }'

curl -X POST /api/admin/stripe/promo-codes \
  -H "Content-Type: application/json" \
  -d '{
    "code": "FIRSTORDER",
    "coupon": "coupon_1234567890",
    "restrictions": {
      "first_time_transaction": true,
      "minimum_amount": 2500,
      "minimum_amount_currency": "usd"
    }
  }'

curl /api/admin/stripe/promo-codes?limit=20

curl "/api/admin/stripe/promo-codes?coupon=coupon_1234567890"

curl -X PATCH /api/admin/stripe/promo-codes \
  -H "Content-Type: application/json" \
  -d '{
    "id": "promo_1234567890",
    "active": false
  }'

On this page