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

# Get a coupon

`GET /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/get.ts> (a function with typed inputs; its response is checked against the schema)

Retrieve a coupon. Requires the `coupons:read` scope. A deleted coupon, or one from the other environment, returns `404`.

## Path parameters

- `couponId` string, uuid, required

## Response `200`

Coupon found.

- 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

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

## Changes

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

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