---
title: "Update Coupon"
method: PUT
path: "/v1/coupons/{coupon_id}"
---

# Update Coupon

`PUT /v1/coupons/{coupon_id}`

## Request

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

Replace a coupon's settings. This is a full update: send every required field, even the ones that don't change (sending only some fields returns 422). Omitting `starts_at`, `ends_at`, `coupons_left` or `banner_text` keeps their current values. For `coupon_type` 2 or 3, `applies_to_ids` replaces the current list.

## Path parameters

- `coupon_id` string, uuid, required

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

200

- 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

- `403`: The coupon belongs to another business
- `404`: Coupon not found
- `422`: Validation error

## Changes

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

[Operation history](https://skmtc.dev/hitpayapp/apis/hitpay-api/changes/v1/coupons/:coupon_id/put.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)