Promotion Codes

Create and manage promotion codes. Promotion codes are the customer-facing discount codes generated from coupon templates and applied at checkout.

The Promotion Code object

Attributes
idstring
objectstring
codestring

Customer-facing code, normalized to uppercase (e.g. SUMMER50)

couponstring

ID of the parent coupon

customernullable string

ID of the customer this code is restricted to, if any

activeboolean
first_time_transactionboolean

If true, only redeemable on a customer's first transaction

max_redemptionsnullable integer
max_customer_redemptionsnullable integer
times_redeemedinteger
minimum_amount_centsnullable integer
minimum_amount_currencynullable string
expires_atnullable integer

Unix timestamp

is_expiredboolean
is_maxed_outboolean
is_redeemableboolean

True when active, not expired, and not maxed out

remaining_redemptionsnullable integer
is_customer_specificboolean
livemodeboolean
created_atinteger

Unix timestamp

THE PROMOTION CODE OBJECT
{
  "id": null,
  "object": "promotion_code",
  "code": null,
  "coupon": null,
  "customer": null,
  "active": false,
  "first_time_transaction": false,
  "max_redemptions": null,
  "max_customer_redemptions": null,
  "times_redeemed": 0,
  "minimum_amount_cents": null,
  "minimum_amount_currency": "usd",
  "expires_at": null,
  "is_expired": false,
  "is_maxed_out": false,
  "is_redeemable": false,
  "remaining_redemptions": null,
  "is_customer_specific": false,
  "livemode": false,
  "created_at": 0
}

List promotion codes

Returns a list of promotion codes. The promotion codes are returned sorted by creation date, with the most recent codes appearing first. Use the filtering parameters to narrow results by coupon, customer, active status, or first-time-transaction restriction.

Query parameters
pageintegeroptional

The page offset for fetching data.

per_pageintegeroptional

A limit on the number of objects to be returned. Range: 1 to 100, default is 10.

coupon_idstringoptional

Filter promotion codes by parent coupon ID.

customerstringoptional

Filter promotion codes by customer ID.

activebooleanoptional

Filter by active status (true or false).

first_time_transactionbooleanoptional

Filter codes restricted to first-time transactions only.

Returns

A dictionary with a data property containing an array of promotion code objects, sorted by creation date descending.

GET/v1/promotion_codes
curl --request GET \
  --url https://api.framepayments.com/v1/promotion_codes \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v1/promotion_codes",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "4fe2ab9d-a530-408a-9fa6-42fa44febd88",
      "code": "PROMO6RSG3Q",
      "active": true,
      "livemode": false,
      "first_time_transaction": false,
      "max_redemptions": 100,
      "max_customer_redemptions": 1,
      "times_redeemed": 0,
      "coupon": "32f31673-6a1b-4801-b218-70826a9d1a84",
      "customer": null,
      "minimum_amount_cents": 0,
      "minimum_amount_currency": "usd",
      "expires_at": null,
      "created_at": 1781115885,
      "object": "promotion_code",
      "is_expired": false,
      "is_maxed_out": false,
      "is_redeemable": true,
      "remaining_redemptions": 100,
      "is_customer_specific": false
    }
  ]
}

Create a promotion code

Creates a new promotion code object. Promotion codes are customer-facing discount codes generated from coupon templates — while coupons define the discount structure and rules, promotion codes are the actual codes that customers enter at checkout. The code string is automatically normalized to uppercase (e.g., "summer50" becomes "SUMMER50"). Returns a promotion code object if the call succeeded.

Query parameters
codestringrequired

The promotion code that customers will enter at checkout. Will be automatically converted to uppercase.

coupon_idstringrequired

The ID of the coupon template this promotion code is based on.

activebooleanoptional

Whether this promotion code is currently active and can be used. Default is true.

first_time_transactionbooleanoptional

If true, this code can only be used by customers making their first purchase. Default is false.

max_redemptionsintegeroptional

Maximum number of times this promotion code can be redeemed. Leave null for unlimited redemptions.

minimum_amount_centsintegeroptional

Minimum order amount in cents required to use this promotion code (e.g., 5000 for $50.00).

minimum_amount_currencystringoptional

Currency code for the minimum order amount (e.g., "USD", "EUR", "GBP"). Default is "USD".

expires_atstringoptional

Date and time when this promotion code expires (ISO 8601 format). Leave null for no expiration.

customerstringoptional

If provided, restricts this promotion code to a specific customer only.

Returns

Returns the newly created promotion code object.

POST/v1/promotion_codes
curl --request POST \
  --url https://api.framepayments.com/v1/promotion_codes \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "888652fc-f2f7-4826-9931-3ae635eafbb4",
  "code": "WELCOME20",
  "active": true,
  "livemode": false,
  "first_time_transaction": false,
  "max_redemptions": null,
  "max_customer_redemptions": 1,
  "times_redeemed": 0,
  "coupon": "03f40681-550e-46fd-9f07-eb0fc1dbc558",
  "customer": null,
  "minimum_amount_cents": 0,
  "minimum_amount_currency": "usd",
  "expires_at": 1783707885,
  "created_at": 1781115885,
  "object": "promotion_code",
  "is_expired": false,
  "is_maxed_out": false,
  "is_redeemable": true,
  "remaining_redemptions": null,
  "is_customer_specific": false
}

Retrieve a promotion code

Retrieves the details of an existing promotion code. You need only supply the unique promotion code identifier that was returned upon promotion code creation. Returns a promotion code object if a valid identifier was provided.

Path parameters
idstringrequired

The unique identifier of the promotion code to retrieve.

Returns

Returns the promotion code object for the given ID.

GET/v1/promotion_codes/{id}
curl --request GET \
  --url https://api.framepayments.com/v1/promotion_codes/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "cec3bb78-bd14-49a4-9518-95b8ae88ddf0",
  "code": "PROMOZMKVSK",
  "active": true,
  "livemode": false,
  "first_time_transaction": false,
  "max_redemptions": 100,
  "max_customer_redemptions": 1,
  "times_redeemed": 0,
  "coupon": "82d1394a-59d2-4838-a1b2-a9aecd0aa3ef",
  "customer": null,
  "minimum_amount_cents": 0,
  "minimum_amount_currency": "usd",
  "expires_at": null,
  "created_at": 1781115885,
  "object": "promotion_code",
  "is_expired": false,
  "is_maxed_out": false,
  "is_redeemable": true,
  "remaining_redemptions": 100,
  "is_customer_specific": false
}

Update a promotion code

Updates the specific promotion code by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns the promotion code object if the update succeeded.

Path parameters
idstringrequired

The unique identifier of the promotion code to update.

Query parameters
codestringoptional

Update the promotion code. Will be automatically converted to uppercase.

activebooleanoptional

Update whether this promotion code is active and can be used.

customerstringoptional

Update or set customer restriction. Set to a customer ID to restrict usage, or null to remove restriction.

first_time_transactionbooleanoptional

Update whether this code is restricted to first-time customers only.

max_redemptionsintegeroptional

Update the maximum number of redemptions allowed.

minimum_amount_centsintegeroptional

Update the minimum order amount in cents.

minimum_amount_currencystringoptional

Update the currency for minimum order amount.

expires_atstringoptional

Update the expiration date and time (ISO 8601 format). Set to null to remove expiration.

Returns

Returns the updated promotion code object.

PATCH/v1/promotion_codes/{id}
curl --request PATCH \
  --url https://api.framepayments.com/v1/promotion_codes/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "08a4a1b8-6f2d-4c53-8193-b43ff3fc88cb",
  "code": "PROMOLMH36T",
  "active": false,
  "livemode": false,
  "first_time_transaction": false,
  "max_redemptions": 100,
  "max_customer_redemptions": 1,
  "times_redeemed": 0,
  "coupon": "f5da2ba3-f4e3-494e-9c29-58878623db3d",
  "customer": null,
  "minimum_amount_cents": 0,
  "minimum_amount_currency": "usd",
  "expires_at": null,
  "created_at": 1781115885,
  "object": "promotion_code",
  "is_expired": false,
  "is_maxed_out": false,
  "is_redeemable": false,
  "remaining_redemptions": 100,
  "is_customer_specific": false
}