FlintflintDocs

Coupons

Coupons are reusable discounts applied to orders and checkout flows. Each coupon offers either a percentage or a fixed amount off, and can carry a redeemable code or be codeless for programmatic application. Usage limits, expiration, minimum purchase amounts, stackability, and catalog restrictions (specific products, variants, bundles, or categories) control where and how often a coupon applies.

A coupon's effective status is computed: active, disabled (merchant-toggled, reversible), expired (past expires_at), exhausted (usage limit reached), or deleted. Applying a coupon to an order creates an order discount; one-off price adjustments that don't need a reusable coupon can use manual discounts on the order directly.

Coupons cover the simple, single-code case. When you need automatic (codeless) discounts, multi-code campaigns, buy-X-get-Y, or eligibility and stacking rules, reach for Promotions: a coupon is a promotion with the common case pre-flattened into one code and a flat set of restrictions.

Coupon metadata is caller-owned. Keys starting with flint_ are reserved for Flint internals and cannot be written through the public API.

Endpoints

List coupons#

GET/v1/couponsRequires scope: commerce.coupons.read or commerce.coupons.write

Returns a paginated list of coupons for the authenticated merchant.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

statusenum

Filter by coupon status.

activedisabledexpiredexhausteddeleted
querystring

Search across coupon name and code.

product_idstring

Filter coupons that apply to a given product, including universal coupons.

variant_idstring

Filter coupons that apply to a given product variant, including universal coupons.

bundle_idstring

Filter coupons that apply to a given bundle, including universal coupons.

categorystring

Filter coupons that apply to a normalized category, including universal coupons.

sort_byenum

Sort field.

namecreated_atupdated_atexpires_at
sort_directionenum

Sort direction.

ascdesc
created_afterstring

RFC3339 lower bound for created_at.

created_beforestring

RFC3339 upper bound for created_at.

updated_afterstring

RFC3339 lower bound for updated_at.

updated_beforestring

RFC3339 upper bound for updated_at.

expires_afterstring

RFC3339 lower bound for expires_at.

expires_beforestring

RFC3339 upper bound for expires_at.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/coupons \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "coupon_id": "promo_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J",
      "name": "Spring Sale",
      "status": "active",
      "metadata": {
        "campaign": "spring_launch"
      },
      "restrictions": {
        "product_ids": [
          "prod_123"
        ]
      },
      "merchant_id": "mer_123",
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z",
      "percent_off": 15,
      "coupon_code": "SPRING15",
      "max_uses": 500,
      "uses_count": 24,
      "expires_at": "2026-04-01T00:00:00Z",
      "minimum_purchase_money": {
        "amount": 5000,
        "currency": "USD"
      },
      "is_stackable": false,
      "calculation_basis": "subtotal_pre_tax"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create coupon#

POST/v1/couponsIdempotentRequires scope: commerce.coupons.write

Creates a coupon for the authenticated merchant.

Request body
option 1object
option 2object
Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl -X POST https://api.withflintpay.com/v1/coupons \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "name": "Spring Sale",
    "percent_off": 15,
    "coupon_code": "SPRING15",
    "max_uses": 500,
    "expires_at": "2026-04-01T00:00:00Z",
    "metadata": {
      "campaign": "spring_launch"
    },
    "restrictions": {
      "product_ids": [
        "prod_123"
      ]
    },
    "minimum_purchase_money": {
      "amount": 5000,
      "currency": "USD"
    },
    "is_stackable": false,
    "calculation_basis": "subtotal_pre_tax"
  }'
JSON
{
  "data": {
    "coupon_id": "promo_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J",
    "name": "Spring Sale",
    "status": "active",
    "metadata": {
      "campaign": "spring_launch"
    },
    "restrictions": {
      "product_ids": [
        "prod_123"
      ]
    },
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "percent_off": 15,
    "coupon_code": "SPRING15",
    "max_uses": 500,
    "uses_count": 24,
    "expires_at": "2026-04-01T00:00:00Z",
    "minimum_purchase_money": {
      "amount": 5000,
      "currency": "USD"
    },
    "is_stackable": false,
    "calculation_basis": "subtotal_pre_tax"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get coupon#

GET/v1/coupons/{coupon_id}Requires scope: commerce.coupons.read or commerce.coupons.write

Returns a single coupon by ID.

Path parameters
coupon_idstringrequired

Flint coupon ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/coupons/promo_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "coupon_id": "promo_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J",
    "name": "Spring Sale",
    "status": "active",
    "metadata": {
      "campaign": "spring_launch"
    },
    "restrictions": {
      "product_ids": [
        "prod_123"
      ]
    },
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "percent_off": 15,
    "coupon_code": "SPRING15",
    "max_uses": 500,
    "uses_count": 24,
    "expires_at": "2026-04-01T00:00:00Z",
    "minimum_purchase_money": {
      "amount": 5000,
      "currency": "USD"
    },
    "is_stackable": false,
    "calculation_basis": "subtotal_pre_tax"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update coupon#

PATCH/v1/coupons/{coupon_id}IdempotentRequires scope: commerce.coupons.write

Applies a sparse update to coupon scalar, metadata, status, and discount fields. Use the coupon restrictions replace endpoint to change catalog applicability.

Path parameters
coupon_idstringrequired

Flint coupon ID.

Request body
amount_off_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

calculation_basisenum
subtotal_pre_taxsubtotal_post_tax
coupon_codestring
descriptionstring
expires_atstring

RFC3339 timestamp.

is_stackableboolean
max_usesinteger
metadatamap of string

Caller-owned metadata. Keys starting with flint_ are reserved and cannot be written through the public API.

minimum_purchase_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

namestring
percent_offnumber
statusenum
activedisabled
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PATCH https://api.withflintpay.com/v1/coupons/promo_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "description": "15% off spring ticket sales",
    "status": "disabled"
  }'
JSON
{
  "data": {
    "coupon_id": "promo_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J",
    "name": "Spring Sale",
    "status": "active",
    "metadata": {
      "campaign": "spring_launch"
    },
    "restrictions": {
      "product_ids": [
        "prod_123"
      ]
    },
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "percent_off": 15,
    "coupon_code": "SPRING15",
    "max_uses": 500,
    "uses_count": 24,
    "expires_at": "2026-04-01T00:00:00Z",
    "minimum_purchase_money": {
      "amount": 5000,
      "currency": "USD"
    },
    "is_stackable": false,
    "calculation_basis": "subtotal_pre_tax"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Delete coupon#

DELETE/v1/coupons/{coupon_id}IdempotentRequires scope: commerce.coupons.write

Permanently deletes a coupon.

Path parameters
coupon_idstringrequired

Flint coupon ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X DELETE https://api.withflintpay.com/v1/coupons/promo_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "coupon_id": "promo_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J",
    "name": "Spring Sale",
    "status": "active",
    "metadata": {
      "campaign": "spring_launch"
    },
    "restrictions": {
      "product_ids": [
        "prod_123"
      ]
    },
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "percent_off": 15,
    "coupon_code": "SPRING15",
    "max_uses": 500,
    "uses_count": 24,
    "expires_at": "2026-04-01T00:00:00Z",
    "minimum_purchase_money": {
      "amount": 5000,
      "currency": "USD"
    },
    "is_stackable": false,
    "calculation_basis": "subtotal_pre_tax"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Replace coupon restrictions#

PUT/v1/coupons/{coupon_id}/restrictionsIdempotentRequires scope: commerce.coupons.write

Replaces the coupon's catalog applicability membership. Send an empty object to make the coupon universal.

Path parameters
coupon_idstringrequired

Flint coupon ID.

Request body
bundle_idsarray of string
categoriesarray of string
product_idsarray of string
variant_idsarray of string
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PUT https://api.withflintpay.com/v1/coupons/promo_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J/restrictions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "product_ids": [
      "prod_123"
    ]
  }'
JSON
{
  "data": {
    "coupon_id": "promo_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J",
    "name": "Spring Sale",
    "status": "active",
    "metadata": {
      "campaign": "spring_launch"
    },
    "restrictions": {
      "product_ids": [
        "prod_123"
      ]
    },
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "percent_off": 15,
    "coupon_code": "SPRING15",
    "max_uses": 500,
    "uses_count": 24,
    "expires_at": "2026-04-01T00:00:00Z",
    "minimum_purchase_money": {
      "amount": 5000,
      "currency": "USD"
    },
    "is_stackable": false,
    "calculation_basis": "subtotal_pre_tax"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get coupon by code#

GET/v1/coupons/by-code/{coupon_code}Requires scope: commerce.coupons.read or commerce.coupons.write

Returns a single coupon by exact coupon code.

Path parameters
coupon_codestringrequired

Merchant-unique coupon code.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/coupons/by-code/{coupon_code} \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "coupon_id": "promo_01HZYV7Q9Y0Y4H8Q3H9F6R7T8J",
    "name": "Spring Sale",
    "status": "active",
    "metadata": {
      "campaign": "spring_launch"
    },
    "restrictions": {
      "product_ids": [
        "prod_123"
      ]
    },
    "merchant_id": "mer_123",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "percent_off": 15,
    "coupon_code": "SPRING15",
    "max_uses": 500,
    "uses_count": 24,
    "expires_at": "2026-04-01T00:00:00Z",
    "minimum_purchase_money": {
      "amount": 5000,
      "currency": "USD"
    },
    "is_stackable": false,
    "calculation_basis": "subtotal_pre_tax"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}
Rate this doc