---
title: "Update a coupon"
method: PATCH
path: "/v1/coupons/{couponId}"
tags: ["Coupons"]
---

# Update a coupon

`PATCH /v1/coupons/{couponId}`

## Request

- Base URL: `https://api.yuvexpay.com`
- URL: `https://api.yuvexpay.com/v1/coupons/{couponId}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/yuvexpay/apis/yuvexpay-api/docs/v1/coupons/:couponId/patch.ts> (a function with typed inputs; its response is checked against the schema)

Update one or more fields of a coupon. Requires the `coupons:write` scope. The change applies from the next time the coupon is applied; a payment that already holds the coupon keeps it.

## Path parameters

- `couponId` string, uuid, required

## Request body

- UpdateCouponRequest: Send only the fields to change. `null` clears a nullable field. Changing `type` without the value of the new type returns `400 COUPON_VALUE_INVALID`, since the value of the old type is cleared.
  - `code` string: 3 to 32 characters from `A-Z`, `0-9`, `_` and `-`, after trimming. Stored uppercase, so `black10` is saved as `BLACK10`. Unique among the coupons of your account in this environment that are not deleted (`409 COUPON_CODE_TAKEN`).
  - `type` 'PERCENT' | 'FIXED'
  - `percentBp` integer, nullable
  - `amount` number, nullable
  - `validFrom` string, date-time, nullable
  - `validUntil` string, date-time, nullable
  - `maxRedemptions` integer, nullable
  - `maxRedemptionsPerBuyer` integer, nullable
  - `productIds` string[]: Replaces the whole list.
  - `active` boolean

## Response `200`

Coupon updated.

- object
  - `coupon` Coupon, required
    - `id` string, uuid, required
    - `code` string, required: Uppercase code, 3 to 32 characters from `A-Z`, `0-9`, `_` and `-`.
    - `type` 'PERCENT' | 'FIXED', required
    - `percentBp` integer, nullable, required: `PERCENT` only: the discount in basis points, `1500` for 15% and `10000` for 100%. `null` on a `FIXED` coupon.
    - `amount` number, nullable, required: `FIXED` only: the discount in BRL. `null` on a `PERCENT` coupon.
    - `validFrom` string, date-time, nullable, required: The coupon works from this time on, inclusive. `null`: no start.
    - `validUntil` string, date-time, nullable, required: The coupon stops working at this time, exclusive. `null`: no end.
    - `maxRedemptions` integer, nullable, required: Total uses. `null`: no limit.
    - `maxRedemptionsPerBuyer` integer, nullable, required: Uses per payer e-mail. `null`: no limit.
    - `productIds` string[], required: Products the discount covers. Empty: the whole order.
    - `active` boolean, required
    - `redemptionCount` integer, required: Uses taken: payments holding the coupon that are still open, plus the completed ones. A payment that expires or is cancelled gives its use back.
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required

## Other responses

- `400`: Validation failed. Besides `VALIDATION_ERROR`: `COUPON_VALUE_INVALID`, `percentBp` and `amount` do not match `type`; `COUPON_WINDOW_INVALID`, `validUntil` is not after `validFrom`; `COUPON_PRODUCT_NOT_FOUND`, a `productIds` entry is not a product of your account in this environment.
- `401`: Missing or invalid authentication token.
- `403`: The API key is valid but does not have the required scope for this endpoint.
- `404`: Resource not found.
- `409`: `COUPON_CODE_TAKEN`: another coupon of your account in this environment that is not deleted has this code.

## Changes

- **2026-10-31** `5236ef291a8e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/yuvexpay/apis/yuvexpay-api/changes/v1/coupons/:couponId/patch.md)

---

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