Sign in
Promo Codes

List Promo Codes

Lists promo codes for an account with cursor pagination, filters, and sorting.

get/promo_codes

Query parameters

account_idstring required

Account whose promo codes are listed (biz_ tag).

status'active' | 'inactive' | 'archived' | 'expired'

Promo-code status. expired groups inactive and archived codes.

product_idsstring[]

Only promo codes scoped to these product IDs.

[
  "prod_xxxxxxxxxxxxxx"
]
plan_idsstring[]

Only promo codes scoped to these plan IDs.

[
  "plan_xxxxxxxxxxxxxx"
]
created_beforestring date-time

Only promo codes created before this ISO 8601 timestamp.

created_afterstring date-time

Only promo codes created after this ISO 8601 timestamp.

order'created_at'

Sort field.

direction'asc' | 'desc'

Sort direction.

firstinteger

Number of results to return from the start of the range.

afterstring

Return results after this cursor. Use page_info.end_cursor from the previous response to fetch the next page.

lastinteger

Number of results to return from the end of the range.

beforestring

Return results before this cursor. Use page_info.start_cursor from the previous response to fetch the previous page.

Response

promo codes listed

Example response

{
  "data": [
    {
      "amount_off": 0.1,
      "code": "welcome",
      "created_at": "2026-01-01T12:00:00.000Z",
      "currency": "usd",
      "duration": "repeating",
      "expires_at": "2026-01-01T12:00:00.000Z",
      "id": "promo_xxxxxxxxxxxxxx",
      "metadata": {},
      "new_users_only": true,
      "one_per_customer": true,
      "product": {
        "id": "prod_xxxxxxxxxxxxxx",
        "title": "Ceramic Coating Package"
      },
      "promo_duration_months": 1,
      "promo_type": "percentage",
      "status": "active",
      "stock": 25,
      "updated_at": "2026-01-01T12:00:00.000Z",
      "uses": 1
    }
  ],
  "page_info": {
    "start_cursor": "WyJjdXJzb3IiLDFd"
  }
}

Changes