Promotion Codes

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 to receive discounts. This separation allows merchants to create multiple promotional codes from a single coupon template, each with unique targeting, expiration dates, and usage limits.

ENDPOINTS

POST/v1/promotion_codes

PATCH/v1/promotion_codes/:id

GET/v1/promotion_codes

GET/v1/promotion_codes/:id

The Promotion Code object

Attributes

idstringoptional

Unique identifier for the object.

codestringoptional

The promotion code that customers enter at checkout. Automatically normalized to uppercase (e.g., "SUMMER50", "WELCOME2025").

couponstringoptional

The ID of the coupon template this promotion code is based on. The promotion code inherits discount configuration from this coupon.

customernullable stringoptional

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

activebooleanoptional

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

first_time_transactionbooleanoptional

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

max_redemptionsnullable integeroptional

Maximum number of times this promotion code can be redeemed across all customers. Null for unlimited redemptions.

times_redeemedintegeroptional

Current count of how many times this promotion code has been redeemed.

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.

expires_atnullable timestampoptional

Date and time when this promotion code expires.

is_expiredbooleanoptional

Whether the promotion code has passed its expiration date.

is_maxed_outbooleanoptional

Whether the promotion code has reached its maximum redemption limit.

is_redeemablebooleanoptional

Whether the promotion code can currently be used (active, not expired, not maxed out).

remaining_redemptionsnullable integeroptional

Number of redemptions remaining before hitting the limit. Null if no limit set.

is_customer_specificbooleanoptional

Whether this promotion code is restricted to a specific customer.

metadatadictionaryoptional

A metadata object consists of key-value pairs that can be attached to Frame object. Use metadata to store structured, additional information about the object for your reference. Learn more about storing information in metadata.

livemodebooleanoptional

Has the value true if the object exists in live mode or the value false if the object exists in test mode.

created_attimestampoptional

Time at which the object was created.

objectstringoptional

String representing the object’s type. Objects of the same type share the same value. Always has the value promotion_code.

THE PROMOTION CODE OBJECT

{
  "id": "9b2adad0-d2b7-41aa-aa8c-c1c45060b0a4",
  "code": "SUMMER50",
  "minimum_amount_currency": "USD",
  "expires_at": 1769903999,
  "created_at": 1768251304,
  "object": "promotion_code",
  "is_expired": false,
  "is_maxed_out": false,
  "is_redeemable": true,
  "remaining_redemptions": 50,
  "is_customer_specific": false,
  "active": true,
  "livemode": false,
  "first_time_transaction": true,
  "max_redemptions": 50,
  "times_redeemed": 0,
  "coupon": "a2b43435-cdd9-44bb-8b7a-c3ad0ec8b3e2",
  "customer": null,
  "minimum_amount_cents": 5000
}

Create a promotion code

Creates a new promotion code object.

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.

customerstringoptional

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

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.

metadatadictionaryoptional

Returns

Returns a promotion code object if the call succeeded.

POST/v1/promotion_codes

curl --request POST \
  --url https://api.framepayments.com/v1/promotion_codes \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "code": "SUMMER50",
  "coupon_id": "a2b43435-cdd9-44bb-8b7a-c3ad0ec8b3e2",
  "active": true,
  "first_time_transaction": true,
  "max_redemptions": 100,
  "minimum_amount_cents": 5000,
  "minimum_amount_currency": "USD",
  "expires_at": "2026-08-31T23:59:59Z"
}'

RESPONSE

{
  "id": "9b2adad0-d2b7-41aa-aa8c-c1c45060b0a4",
  "code": "SUMMER50",
  "minimum_amount_currency": "USD",
  "expires_at": 1769903999,
  "created_at": 1768251304,
  "object": "promotion_code",
  "is_expired": false,
  "is_maxed_out": false,
  "is_redeemable": true,
  "remaining_redemptions": 50,
  "is_customer_specific": false,
  "active": true,
  "livemode": false,
  "first_time_transaction": true,
  "max_redemptions": 50,
  "times_redeemed": 0,
  "coupon": "a2b43435-cdd9-44bb-8b7a-c3ad0ec8b3e2",
  "customer": null,
  "minimum_amount_cents": 5000
}

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.

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.

metadatadictionaryoptional

Returns

Returns the promotion code object if the update succeeded.

PATCH/v1/promotion_codes/:id

curl --request PATCH \
  --url https://api.framepayments.com/v1/promotion_codes/9b2adad0-d2b7-41aa-aa8c-c1c45060b0a4 \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "code": "SUMMER50",
  "active": true,
  "first_time_transaction": true,
  "max_redemptions": 50,
  "minimum_amount_cents": 5000,
  "minimum_amount_currency": "USD",
  "expires_at": "2026-01-31T23:59:59Z"
}'

RESPONSE

{
  "id": "9b2adad0-d2b7-41aa-aa8c-c1c45060b0a4",
  "code": "SUMMER50",
  "minimum_amount_currency": "USD",
  "expires_at": 1769903999,
  "created_at": 1768251304,
  "object": "promotion_code",
  "is_expired": false,
  "is_maxed_out": false,
  "is_redeemable": true,
  "remaining_redemptions": 50,
  "is_customer_specific": false,
  "active": true,
  "livemode": false,
  "first_time_transaction": true,
  "max_redemptions": 50,
  "times_redeemed": 0,
  "coupon": "a2b43435-cdd9-44bb-8b7a-c3ad0ec8b3e2",
  "customer": null,
  "minimum_amount_cents": 5000
}

List all promotion codes

Returns a list of promotion codes. The promotion codes are returned sorted by creation date, with the most recent codes appearing first.

Parameters

per_pageintegeroptional

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

pageintegeroptional

The page offset for fetching data.

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 that contains an array of promotion code objects. Each entry in the array is a separate promotion code object. If no promotion codes are available, the resulting array will be empty.

GET/v1/promotion_codes

curl --request GET \
  --url 'https://api.framepayments.com/v1/promotion_codes?per_page=10&page=1&active=true' \
  --header 'Authorization: Bearer API_KEY'

RESPONSE

{
  "data": [
    {
      "id": "9b2adad0-d2b7-41aa-aa8c-c1c45060b0a4",
      "code": "SUMMER50",
      "minimum_amount_currency": "USD",
      "expires_at": 1769903999,
      "created_at": 1768251304,
      "object": "promotion_code",
      "is_expired": false,
      "is_maxed_out": false,
      "is_redeemable": true,
      "remaining_redemptions": 50,
      "is_customer_specific": false,
      "active": true,
      "livemode": false,
      "first_time_transaction": true,
      "max_redemptions": 50,
      "times_redeemed": 0,
      "coupon": "a2b43435-cdd9-44bb-8b7a-c3ad0ec8b3e2",
      "customer": null,
      "minimum_amount_cents": 5000
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 10,
    "total": 1,
    "url": "/v1/promotion_codes",
    "has_more": false,
    "prev": null,
    "next": null
  }
}

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.

Parameters

No parametersoptional

Returns

Returns a promotion code object if a valid identifier was provided.

GET/v1/promotion_codes/:id

curl --request GET \
  --url https://api.framepayments.com/v1/promotion_codes/9b2adad0-d2b7-41aa-aa8c-c1c45060b0a4 \
  --header 'Authorization: Bearer API_KEY'

RESPONSE

{
  "id": "9b2adad0-d2b7-41aa-aa8c-c1c45060b0a4",
  "code": "SUMMER50",
  "minimum_amount_currency": "USD",
  "expires_at": 1769903999,
  "created_at": 1768251304,
  "object": "promotion_code",
  "is_expired": false,
  "is_maxed_out": false,
  "is_redeemable": true,
  "remaining_redemptions": 50,
  "is_customer_specific": false,
  "active": true,
  "livemode": false,
  "first_time_transaction": true,
  "max_redemptions": 50,
  "times_redeemed": 0,
  "coupon": "a2b43435-cdd9-44bb-8b7a-c3ad0ec8b3e2",
  "customer": null,
  "minimum_amount_cents": 5000
}