Create Coupon

Create a coupon code for all products, specific categories, or specific products

POST /v1/coupons

Create Coupon

cURL

curl --request POST \
  --url https://api.hit-pay.com/v1/coupons \
  --header 'Content-Type: application/json' \
  --header 'X-BUSINESS-API-KEY: <x-business-api-key>' \
  --data '
{
  "name": "Year End Sale",
  "code": "YEAREND10",
  "fixed_amount": 5,
  "percentage": 0,
  "is_promo_banner": false,
  "coupons_left": 100,
  "coupon_type": 2,
  "applies_to_ids": [
    "9bd48afd-ed47-4bdb-aac0-388d6b25d199"
  ],
  "minimum_cart_amount": 20,
  "starts_at": "2026-11-01",
  "ends_at": "2026-12-31"
}
'

201

{
  "id": "a304f0fd-4ebb-4a8f-bc90-c7341f90080c",
  "business_id": "98567029-f559-49f9-916b-042a4255b32a",
  "name": "Year End Sale",
  "code": "YEAREND10",
  "fixed_amount": 500,
  "percentage": 0,
  "coupons_left": 100,
  "is_promo_banner": false,
  "banner_text": null,
  "created_at": "2026-10-19T13:23:03.000000Z",
  "updated_at": "2026-10-19T13:23:03.000000Z",
  "starts_at": "2026-10-31T16:00:00.000000Z",
  "ends_at": "2026-12-30T16:00:00.000000Z",
  "coupon_type": 2,
  "minimum_cart_amount": 2000,
  "deleted_at": null,
  "applies_to_ids": [
    {
      "id": "9bd48afd-ed47-4bdb-aac0-388d6b25d199",
      "name": "Apparels"
    }
  ]
}

Send fixed_amount and minimum_cart_amount in major currency units (for example 5 = SGD 5.00). Responses return them in minor units (500). percentage is a fraction: 0.15 = 15%.

Headers

X-BUSINESS-API-KEY · string · required

Example:

"b286daabf9921b5a01a4621f026c111e046f8911feba212996c92159b98427d"

Body

application/json

Coupon settings.

name · string · required

Coupon name, shown in the dashboard.

Maximum string length: 64

Example:

"Year End Sale"

code · string · required

Code customers enter at checkout. Must be unique among the business's active coupons.

Maximum string length: 64

Example:

"YEAREND10"

fixed_amount · number · required

Fixed discount amount. Sent in major currency units (for example 5 = SGD 5.00). Responses return it in minor units (cents), for example 500. Send 0 for a percentage-only coupon. fixed_amount and percentage cannot both be 0.

Required range: 0 <= x <= 999999.99

Example:

5

percentage · number · required

Percentage discount as a fraction, up to 4 decimal places (0.15 = 15%). Send 0 for a fixed-amount-only coupon.

Required range: 0 <= x <= 1

Example:

0

is_promo_banner · boolean · required

Show this coupon in the store's promo banner. Setting it to true turns the banner off for every other coupon and discount of the business.

Example:

false

coupon_type · enum<integer> · required

What the coupon applies to: 1 = all products, 2 = specific categories, 3 = specific products.

Available options: 1, 2, 3

Example:

2

minimum_cart_amount · number · required

Minimum cart amount for the coupon to apply. Sent in major currency units (for example 5 = SGD 5.00). Responses return it in minor units (cents), for example 500.

Required range: x >= 0

Example:

20

banner_text · string | null

Text for the promo banner.

Maximum string length: 1000

Example:

null

coupons_left · integer | null

How many times the coupon can still be used. Omit or send null for unlimited.

Example:

100

applies_to_ids · string[]

Category IDs (coupon_type 2) or product IDs (coupon_type 3). Required for types 2 and 3, ignored for type 1.

Maximum string length: 36

Example:

["9bd48afd-ed47-4bdb-aac0-388d6b25d199"]

starts_at · string<date> | null

When the coupon becomes valid, read in the business's timezone. Omit for no start date.

Example:

"2026-11-01"

ends_at · string<date> | null

When the coupon expires, read in the business's timezone. Must be on or after starts_at. Omit for no end date.

Example:

"2026-12-31"

Response

201

application/json

201

id · string<uuid>

business_id · string<uuid>

name · string

code · string

fixed_amount · integer

Fixed discount in minor units (cents).

percentage · number

Percentage discount as a fraction (0.15 = 15%).

coupons_left · integer | null

Remaining uses; null = unlimited.

is_promo_banner · boolean

banner_text · string | null

created_at · string<date-time>

updated_at · string<date-time>

starts_at · string<date-time> | null

UTC.

ends_at · string<date-time> | null

UTC.

coupon_type · enum<integer>

Available options: 1, 2, 3

minimum_cart_amount · integer

Minimum cart amount in minor units (cents).

deleted_at · string<date-time> | null

applies_to_ids · object[]

Categories or products the coupon applies to. Empty for coupon_type 1.

Show child attributes