HIhitpayapp

Create Coupon

Changed on

Create a coupon code customers can use at checkout. Amounts are sent in major currency units and returned in minor units (cents).

post/v1/coupons

Request

  • Base URL
    https://api.hit-pay.com
  • URL
    https://api.hit-pay.com/v1/coupons
  • Auth
    none declared. Required headers: X-BUSINESS-API-KEY

Headers

X-BUSINESS-API-KEYstring required
Example:b286daabf9921b5a01a4621f026c111e046f8911feba212996c92159b98427d

Request body

namestring required

Coupon name, shown in the dashboard.

codestring required

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

fixed_amountnumber 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.

percentagenumber required

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

is_promo_bannerboolean 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.

banner_textstring nullable

Text for the promo banner.

coupons_leftinteger nullable

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

coupon_type1 | 2 | 3 required

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

applies_to_idsstring[]

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

minimum_cart_amountnumber 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.

starts_atstring date nullable

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

ends_atstring date nullable

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

Example request

{
  "name": "Year End Sale",
  "code": "YEAREND10",
  "fixed_amount": 5,
  "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"
}

Response

201

idstring uuid
business_idstring uuid
namestring
codestring
fixed_amountinteger

Fixed discount in minor units (cents).

percentagenumber

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

coupons_leftinteger nullable

Remaining uses; null = unlimited.

is_promo_bannerboolean
banner_textstring nullable
created_atstring date-time
updated_atstring date-time
starts_atstring date-time nullable

UTC.

ends_atstring date-time nullable

UTC.

coupon_type1 | 2 | 3
minimum_cart_amountinteger

Minimum cart amount in minor units (cents).

deleted_atstring date-time nullable

Changes