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

Changed in 2 of the 74 revisions of this API.101222

  • f1020c3ecda43See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    This revision also has 9 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • bdd0e2c70d58101219See the full diff
    • ▲

      added the new required query request parameter account_id

      new-required-request-parameter

    • ▲

      the query request parameter status was restricted to a list of enum values

      request-parameter-became-enum

    • ▲

      for the query request parameter first, default value 20 was added

      request-parameter-default-value-added

    • ▲

      added subschema #2 to the // response property oneOf list for the response status

      response-property-one-of-added

    • ▲

      the // response's property format changed from date-time to no format for status

      response-property-type-changed

    • ▲

      the // response's property type changed from no type to string for status

      response-property-type-changed

    • ▲

      the // response's property format changed from date-time to no format for status

      response-property-type-changed

    • ▲

      the // response's property type changed from object null to no type for status

      response-property-type-changed

    • ▲

      removed the required property /// from the response with the status

      response-required-property-removed

    • ▲

      removed the required property /// from the response with the status

      response-required-property-removed

    • ●

      for the query request parameter first, the max was set to 100.00

      request-parameter-max-set

    • ●

      for the query request parameter last, the max was set to 100.00

      request-parameter-max-set

    • ●

      deleted the query request parameter company_id

      request-parameter-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      added the new forever enum value to the // response property for the response status

      response-property-enum-value-added

    • ●

      added the new once enum value to the // response property for the response status

      response-property-enum-value-added

    • ●

      added the new repeating enum value to the // response property for the response status

      response-property-enum-value-added

    • ○

      api operation id listPromoCode removed and replaced with listPromoCodes

      api-operation-id-removed

    • ○

      the security scope access_pass:basic:read was removed from the endpoint's security scheme bearerAuth

      api-security-scope-removed

    • ○

      api tag Promo Codes added

      api-tag-added

    • ○

      api tag Promo codes removed

      api-tag-removed

    • ○

      added the new optional header request parameter Api-Version-Date to all path's operations

      new-optional-request-default-parameter-to-existing-path

    • ○

      added the new optional query request parameter direction

      new-optional-request-parameter

    • ○

      added the new optional query request parameter order

      new-optional-request-parameter

    • ○

      added the new enum value active to the query request parameter status

      request-parameter-enum-value-added

    • ○

      added the new enum value archived to the query request parameter status

      request-parameter-enum-value-added

    • ○

      added the new enum value expired to the query request parameter status

      request-parameter-enum-value-added

    • ○

      added the new enum value inactive to the query request parameter status

      request-parameter-enum-value-added

    • ○

      for the query request parameter status, the type was generalized from no type to string

      request-parameter-type-generalized

    • ○

      removed the non-success response with the status

      response-non-success-status-removed

    • ○

      removed the non-success response with the status

      response-non-success-status-removed

    • ○

      removed the non-success response with the status

      response-non-success-status-removed

    • ○

      removed the non-success response with the status

      response-non-success-status-removed

    • ○

      removed subschema #2 from the // response property oneOf list for the response status

      response-property-one-of-removed

    • ○

      added the required property // to the response with the status

      response-required-property-added

    • ○

      added the required property // to the response with the status

      response-required-property-added

    This revision also has 16 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Of the 74 revisions, 1 has no diff computed.