---
title: "List coupons"
method: GET
path: "/v1/coupons"
tags: ["Coupons"]
---

# List coupons

`GET /v1/coupons`

## Request

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

List the coupons of your account that are not deleted, newest first. Requires the `coupons:read` scope. Coupons belong to the environment of the key: a `ypk_test_` key manages sandbox coupons and a `ypk_live_` key production coupons, and a payment uses only coupons of its own environment.

## Query parameters

- `search` string
- `active` 'true' | 'false'
- `page` integer
- `limit` integer

## Response `200`

Coupons listed.

- object
  - `coupons` Coupon[]
    - `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
  - `pagination` Pagination
    - `page` integer
    - `limit` integer
    - `total` integer
    - `totalPages` integer

## Other responses

- `400`: Validation error.
- `401`: Missing or invalid authentication token.
- `403`: The API key is valid but does not have the required scope for this endpoint.

## Changes

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

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