Coupons

Create and manage coupon templates. Coupons define the discount rules — percentage or fixed — that promotion codes are generated from.

The Coupon object

Attributes
idstring
objectstring
namestring

Unique identifier meant to be displayable (e.g. SUMMER2024)

descriptionnullable string
discount_typeenum

One of percentage or fixed_amount.

discount_valuestring

0–100 for percentage; currency value for fixed_amount

discount_value_currencynullable string
durationenum

One of once, repeating, or forever.

duration_in_monthsnullable integer

Required when duration is 'repeating'

statusenum

One of active, inactive, archived, or deleted.

applicable_toenum

One of all_products or specific_products.

product_idnullable string

Present when applicable_to is 'specific_products'

max_redemptionsnullable integer
times_redeemedinteger
minimum_order_amount_centsnullable integer
minimum_order_amount_currencynullable string
discount_cap_centsnullable integer
discount_cap_currencynullable string
valid_fromnullable integer

Unix timestamp

valid_untilnullable integer

Unix timestamp

is_expiredboolean
is_maxed_outboolean
livemodeboolean
createdinteger

Unix timestamp

THE COUPON OBJECT
{
  "id": null,
  "object": "coupon",
  "name": null,
  "description": null,
  "discount_type": "percentage",
  "discount_value": null,
  "discount_value_currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "status": "active",
  "applicable_to": "all_products",
  "product_id": null,
  "max_redemptions": null,
  "times_redeemed": 0,
  "minimum_order_amount_cents": null,
  "minimum_order_amount_currency": null,
  "discount_cap_cents": null,
  "discount_cap_currency": null,
  "valid_from": null,
  "valid_until": null,
  "is_expired": false,
  "is_maxed_out": false,
  "livemode": false,
  "created": 0
}

List coupons

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

A dictionary with a data property that contains an array of coupon objects is returned. If no coupons are available, the resulting array will be empty.

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.

statusenumoptional

Filter coupons by status. One of active, inactive, archived, or deleted.

discount_typeenumoptional

Filter coupons by discount type. Either percentage or fixed_amount.

applicable_toenumoptional

Filter coupons by applicability. Either all_products or specific_products.

Returns

A dictionary with a data property containing an array of coupon objects.

GET/v1/coupons
curl --request GET \
  --url https://api.framepayments.com/v1/coupons \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v1/coupons?status=",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "535a401b-1057-4e28-b2c5-03792eb96c3d",
      "name": "SpecialPrice657665",
      "description": null,
      "discount_type": "percentage",
      "discount_value": "20.0",
      "discount_value_currency": "usd",
      "duration": "once",
      "duration_in_months": null,
      "status": "active",
      "livemode": false,
      "applicable_to": "all_products",
      "max_redemptions": null,
      "times_redeemed": 0,
      "minimum_order_amount_cents": 0,
      "minimum_order_amount_currency": "usd",
      "discount_cap_cents": null,
      "discount_cap_currency": "usd",
      "valid_from": 1781115871,
      "valid_until": 1783707871,
      "created": 1781115871,
      "object": "coupon",
      "is_expired": false,
      "is_maxed_out": false,
      "product_id": null
    }
  ]
}

Create a coupon

Creates a new coupon object. Each coupon can generate multiple customer-facing promotion codes, enabling sophisticated marketing campaigns with precise control and targeting.

Returns a coupon object if the call succeeded.

Query parameters
namestringrequired

A unique name or identifier for the coupon (e.g., "SUMMER2024").

discount_typeenumrequired

The type of discount. Either percentage or fixed_amount.

discount_valuenumberrequired

The discount amount. For percentage, use a value between 0-100 (e.g., 20 for 20%). For fixed_amount, use the currency value.

durationenumrequired

How long the discount applies. Either once, repeating, or forever.

applicable_toenumrequired

Which products the coupon applies to. Either all_products or specific_products.

descriptionstringoptional

A brief description of the coupon's purpose.

duration_in_monthsintegeroptional

Number of months the discount applies. Required when duration is repeating.

statusenumoptional

Initial status of the coupon. Either active or inactive.

max_redemptionsintegeroptional

Maximum number of times this coupon can be redeemed. Null for unlimited.

valid_fromintegeroptional

Date and time when the coupon becomes valid. Provide as seconds since the Unix epoch.

valid_untilintegeroptional

Date and time when the coupon expires. Provide as seconds since the Unix epoch.

Returns

Returns a coupon object if the call succeeded.

POST/v1/coupons
curl --request POST \
  --url https://api.framepayments.com/v1/coupons \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "7a4264ec-acbc-40c2-be60-fea5ddf28368",
  "name": "SUMMER2024",
  "description": null,
  "discount_type": "percentage",
  "discount_value": "20.0",
  "discount_value_currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "status": "active",
  "livemode": false,
  "applicable_to": "all_products",
  "max_redemptions": null,
  "times_redeemed": 0,
  "minimum_order_amount_cents": 0,
  "minimum_order_amount_currency": "usd",
  "discount_cap_cents": null,
  "discount_cap_currency": "usd",
  "valid_from": 1781115871,
  "valid_until": 1783707871,
  "created": 1781115871,
  "object": "coupon",
  "is_expired": false,
  "is_maxed_out": false,
  "product_id": 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.

Returns a coupon object if a valid identifier was provided.

Path parameters
idstringrequired

The unique identifier of the coupon to retrieve.

Returns

Returns a coupon object if a valid identifier was provided.

GET/v1/coupons/{id}
curl --request GET \
  --url https://api.framepayments.com/v1/coupons/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "0acb0cde-c9f5-4db2-a2c2-809e18e2915f",
  "name": "PremiumDiscount999788",
  "description": null,
  "discount_type": "percentage",
  "discount_value": "20.0",
  "discount_value_currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "status": "active",
  "livemode": false,
  "applicable_to": "all_products",
  "max_redemptions": null,
  "times_redeemed": 0,
  "minimum_order_amount_cents": 0,
  "minimum_order_amount_currency": "usd",
  "discount_cap_cents": null,
  "discount_cap_currency": "usd",
  "valid_from": 1781115872,
  "valid_until": 1783707872,
  "created": 1781115872,
  "object": "coupon",
  "is_expired": false,
  "is_maxed_out": false,
  "product_id": null
}

Update a coupon

Updates the specific coupon by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Returns the coupon object if the update succeeded.

Path parameters
idstringrequired

The unique identifier of the coupon to update.

Query parameters
descriptionstringoptional

Update the coupon description.

statusenumoptional

Update the coupon status. Either active or inactive.

max_redemptionsintegeroptional

Update the maximum number of redemptions allowed.

Returns

Returns the coupon object if the update succeeded.

PATCH/v1/coupons/{id}
curl --request PATCH \
  --url https://api.framepayments.com/v1/coupons/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "4cbd673c-a8a0-4139-9f21-64edf43d9d81",
  "name": "IncrediblePromotion572022",
  "description": "Updated description",
  "discount_type": "percentage",
  "discount_value": "20.0",
  "discount_value_currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "status": "active",
  "livemode": false,
  "applicable_to": "all_products",
  "max_redemptions": null,
  "times_redeemed": 0,
  "minimum_order_amount_cents": 0,
  "minimum_order_amount_currency": "usd",
  "discount_cap_cents": null,
  "discount_cap_currency": "usd",
  "valid_from": 1781115872,
  "valid_until": 1783707872,
  "created": 1781115872,
  "object": "coupon",
  "is_expired": false,
  "is_maxed_out": false,
  "product_id": null
}