---
title: "Create Coupon"
method: POST
path: "/v1/coupons"
---

# Create Coupon

`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`

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

## Headers

- `X-BUSINESS-API-KEY` string, required

## Request body

- CouponRequest
  - `name` string, required: Coupon name, shown in the dashboard.
  - `code` string, required: Code customers enter at checkout. Must be unique among the business's active coupons.
  - `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`.
  - `percentage` number, required: Percentage discount as a fraction, up to 4 decimal places (`0.15` = 15%). Send `0` for a fixed-amount-only coupon.
  - `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.
  - `banner_text` string, nullable: Text for the promo banner.
  - `coupons_left` integer, nullable: How many times the coupon can still be used. Omit or send `null` for unlimited.
  - `coupon_type` 1 | 2 | 3, required: What the coupon applies to: `1` = all products, `2` = specific categories, `3` = specific products.
  - `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.
  - `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`.
  - `starts_at` string, date, nullable: When the coupon becomes valid, read in the business's timezone. Omit for no start date.
  - `ends_at` string, date, nullable: When the coupon expires, read in the business's timezone. Must be on or after `starts_at`. Omit for no end date.

## Response `201`

201

- Coupon
  - `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, nullable: Remaining uses; `null` = unlimited.
  - `is_promo_banner` boolean
  - `banner_text` string, nullable
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `starts_at` string, date-time, nullable: UTC.
  - `ends_at` string, date-time, nullable: UTC.
  - `coupon_type` 1 | 2 | 3
  - `minimum_cart_amount` integer: Minimum cart amount in minor units (cents).
  - `deleted_at` string, date-time, nullable
  - `applies_to_ids` object[]: Categories or products the coupon applies to. Empty for `coupon_type` 1.
    - `id` string
    - `name` string

## Other responses

- `422`: Validation error

## Changes

- **2026-11-03** `fac86c13e845`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hitpayapp/apis/hitpay-api/changes/v1/coupons/post.md)

---

[API](https://skmtc.dev/hitpayapp/apis/hitpay-api.md) - [All operations](https://skmtc.dev/hitpayapp/apis/hitpay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hitpayapp/apis/hitpay-api/revisions/fac86c13e845?raw)