Coupons
Coupons are reusable discount templates that define the rules and structure for promotional discounts. Each coupon can generate multiple customer-facing promotion codes, enabling sophisticated marketing campaigns with precise control and targeting. Coupons support percentage or fixed amount discounts, stackable discount logic, multi-currency configuration, and flexible duration options.
The Coupon object
Attributes
Unique identifier for the object.
A unique name or identifier for the coupon, meant to be displayable to the merchant (e.g., "SUMMER2024", "New Customer Discount").
A brief description of the coupon's purpose.
The type of discount applied by this coupon. Either percentage or fixed_amount.
The discount amount. For percentage discounts, this is a value between 0-100 (e.g., "25.0" for 25%). For fixed_amount, this is the currency value (e.g., "10.00").
The currency code for the discount value (e.g., "USD", "EUR", "GBP").
Defines how long the discount remains valid after first use. One of once, repeating, or forever.
The number of months the discount applies. Required when duration is repeating.
Defines which products this coupon can be applied to. Either all_products or specific_products.
The ID of the product this coupon applies to. Required when applicable_to is specific_products.
Maximum number of times this coupon can be redeemed across all customers. Null for unlimited redemptions.
Current count of how many times this coupon has been redeemed.
Minimum order amount in cents required to use this coupon (e.g., 5000 for $50.00).
Currency code for the minimum order amount.
Maximum discount amount in cents that can be applied (e.g., 10000 for $100.00 cap).
Currency code for the discount cap.
Time at which the coupon becomes valid. Measured in seconds since the Unix epoch.
Time at which the coupon expires. Measured in seconds since the Unix epoch.
Current status of the coupon. One of active, inactive, archived, or deleted.
Whether the coupon has passed its expiration date.
Whether the coupon has reached its maximum redemption limit.
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.
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
Time at which the object was created. Measured in seconds since the Unix epoch.
String representing the object’s type. Objects of the same type share the same value. Always has the value coupon.
{
"id": "a2b43435-cdd9-44bb-8b7a-c3ad0ec8b3e2",
"name": "SUMMER2024",
"applicable_to": "all_products",
"max_redemptions": 100,
"times_redeemed": 0,
"minimum_order_amount_cents": 5000,
"minimum_order_amount_currency": "USD",
"discount_cap_cents": 10000,
"discount_cap_currency": "USD",
"valid_from": 1748736000,
"valid_until": 1786147200,
"created": 1768246932,
"description": "Summer sale discount",
"object": "coupon",
"is_expired": false,
"is_maxed_out": false,
"product_id": null,
"discount_type": "percentage",
"discount_value": "20.0",
"discount_value_currency": "USD",
"duration": "repeating",
"duration_in_months": 3,
"status": "active",
"livemode": false
}
Create a coupon
Creates a new coupon object.
Parameters
A unique name or identifier for the coupon (e.g., "SUMMER2024").
A brief description of the coupon's purpose.
The type of discount. Either percentage or fixed_amount.
The discount amount. For percentage, use a value between 0-100 (e.g., 20 for 20%). For fixed_amount, use the currency value.
The currency code for the discount value (e.g., "USD", "EUR", "GBP").
How long the discount applies. Either once, repeating, or forever.
Number of months the discount applies. Required when duration is repeating.
Initial status of the coupon. Either active or inactive.
Which products the coupon applies to. Either all_products or specific_products.
The ID of the product this coupon applies to. Required when applicable_to is specific_products.
Maximum number of times this coupon can be redeemed. Null for unlimited.
Minimum order amount in cents required to use this coupon (e.g., 5000 for $50.00).
Currency code for the minimum order amount.
Maximum discount amount in cents that can be applied (e.g., 10000 for $100.00 cap).
Currency code for the discount cap.
Date and time when the coupon becomes valid. Provide as seconds since the Unix epoch.
Date and time when the coupon expires. Provide as seconds since the Unix epoch.
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.
Returns
Returns a coupon object if the call succeeded.
curl --request POST \
--url https://api.framepayments.com/v1/coupons \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"name": "SUMMER2024",
"description": "Summer sale discount",
"discount_type": "percentage",
"discount_value": 20,
"discount_value_currency": "USD",
"duration": "repeating",
"duration_in_months": 3,
"status": "active",
"applicable_to": "all_products",
"max_redemptions": 100,
"minimum_order_amount_cents": 5000,
"minimum_order_amount_currency": "USD",
"discount_cap_cents": 10000,
"discount_cap_currency": "USD",
"valid_from": "2025-06-01T00:00:00Z",
"valid_until": "2026-08-08T00:00:00Z",
"metadata": {
"campaign": "summer_promo",
"channel": "email"
}
}'
{
"id": "a2b43435-cdd9-44bb-8b7a-c3ad0ec8b3e2",
"name": "SUMMER2024",
"applicable_to": "all_products",
"max_redemptions": 100,
"times_redeemed": 0,
"minimum_order_amount_cents": 5000,
"minimum_order_amount_currency": "USD",
"discount_cap_cents": 10000,
"discount_cap_currency": "USD",
"valid_from": 1748736000,
"valid_until": 1786147200,
"created": 1768246932,
"description": "Summer sale discount",
"object": "coupon",
"is_expired": false,
"is_maxed_out": false,
"product_id": null,
"discount_type": "percentage",
"discount_value": "20.0",
"discount_value_currency": "USD",
"duration": "repeating",
"duration_in_months": 3,
"status": "active",
"livemode": false
}
Update a coupon
Updates the specific coupon by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Parameters
Update the coupon name or identifier.
Update the coupon description.
Update the discount type. Either percentage or fixed_amount.
Update the discount amount.
Update how long the discount applies. Either once, repeating, or forever.
Update the number of months for repeating discounts.
Update the coupon status. Either active or inactive.
Update which products the coupon applies to. Either all_products or specific_products.
Update the product ID when applicable_to is specific_products.
Update the maximum number of redemptions allowed.
Update the minimum order amount in cents.
Update the currency for minimum order amount.
Update the maximum discount amount in cents.
Update the currency for discount cap.
Update when the coupon becomes valid. Provide as seconds since the Unix epoch.
Update when the coupon expires. Provide as seconds since the Unix epoch.
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.
Returns
Returns the coupon object if the update succeeded.
curl --request PATCH \
--url https://api.framepayments.com/v1/coupons/a2b43435-cdd9-44bb-8b7a-c3ad0ec8b3e2 \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"status": "inactive",
"max_redemptions": 150,
"valid_until": "2026-09-30T23:59:59Z"
}'
{
"id": "a2b43435-cdd9-44bb-8b7a-c3ad0ec8b3e2",
"name": "SUMMER2024",
"applicable_to": "all_products",
"max_redemptions": 100,
"times_redeemed": 0,
"minimum_order_amount_cents": 5000,
"minimum_order_amount_currency": "USD",
"discount_cap_cents": 10000,
"discount_cap_currency": "USD",
"valid_from": 1748736000,
"valid_until": 1786147200,
"created": 1768246932,
"description": "Summer sale discount",
"object": "coupon",
"is_expired": false,
"is_maxed_out": false,
"product_id": null,
"discount_type": "percentage",
"discount_value": "20.0",
"discount_value_currency": "USD",
"duration": "repeating",
"duration_in_months": 3,
"status": "active",
"livemode": false
}
List all coupons
Returns a list of coupons. The coupons are returned sorted by creation date, with the most recent coupons appearing first.
Parameters
A limit on the number of objects to be returned. Range: 1 to 100, default is 10.
The page offset for fetching data.
Filter coupons by status. One of active, inactive, archived, or deleted.
Filter coupons by discount type. Either percentage or fixed_amount.
Filter coupons by applicability. Either all_products or specific_products.
Returns
A dictionary with a data property that contains an array of coupon objects. Each entry in the array is a separate coupon object. If no coupons are available, the resulting array will be empty.
curl --request GET \
--url 'https://api.framepayments.com/v1/coupons?per_page=10&page=1&status=active' \
--header 'Authorization: Bearer API_KEY'
{
"data": [
{
"id": "a2b43435-cdd9-44bb-8b7a-c3ad0ec8b3e2",
"name": "SUMMER2024",
"applicable_to": "all_products",
"max_redemptions": 100,
"times_redeemed": 0,
"minimum_order_amount_cents": 5000,
"minimum_order_amount_currency": "USD",
"discount_cap_cents": 10000,
"discount_cap_currency": "USD",
"valid_from": 1748736000,
"valid_until": 1786147200,
"created": 1768246932,
"description": "Summer sale discount",
"object": "coupon",
"is_expired": false,
"is_maxed_out": false,
"product_id": null,
"discount_type": "percentage",
"discount_value": "20.0",
"discount_value_currency": "USD",
"duration": "repeating",
"duration_in_months": 3,
"status": "active",
"livemode": false
}
],
"meta": {
"page": 1,
"per_page": 10,
"total": 1,
"url": "/v1/coupons",
"has_more": false,
"prev": null,
"next": null
}
}
Retrieve a coupon
Retrieves the details of an existing coupon. You need only supply the unique coupon identifier that was returned upon coupon creation.
Parameters
Returns
Returns a coupon object if a valid identifier was provided.
curl --request GET \
--url https://api.framepayments.com/v1/coupons/a2b43435-cdd9-44bb-8b7a-c3ad0ec8b3e2 \
--header 'Authorization: Bearer API_KEY'
{
"id": "a2b43435-cdd9-44bb-8b7a-c3ad0ec8b3e2",
"name": "SUMMER2024",
"applicable_to": "all_products",
"max_redemptions": 100,
"times_redeemed": 0,
"minimum_order_amount_cents": 5000,
"minimum_order_amount_currency": "USD",
"discount_cap_cents": 10000,
"discount_cap_currency": "USD",
"valid_from": 1748736000,
"valid_until": 1786147200,
"created": 1768246932,
"description": "Summer sale discount",
"object": "coupon",
"is_expired": false,
"is_maxed_out": false,
"product_id": null,
"discount_type": "percentage",
"discount_value": "20.0",
"discount_value_currency": "USD",
"duration": "repeating",
"duration_in_months": 3,
"status": "active",
"livemode": false
}