curl --request POST \
--url https://api.yuvexpay.com/v1/coupons \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"code": "black10",
"type": "PERCENT",
"percentBp": 1000,
"validFrom": "2026-11-27T00:00:00-03:00",
"validUntil": "2026-12-01T00:00:00-03:00",
"maxRedemptions": 500,
"maxRedemptionsPerBuyer": 1
}
'{
"coupon": {
"id": "4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e",
"code": "BLACK10",
"type": "PERCENT",
"percentBp": 1000,
"amount": null,
"validFrom": "2026-11-27T03:00:00.000Z",
"validUntil": "2026-12-01T03:00:00.000Z",
"maxRedemptions": 500,
"maxRedemptionsPerBuyer": 1,
"productIds": [],
"active": true,
"redemptionCount": 0,
"createdAt": "2026-10-31T18:00:00.000Z",
"updatedAt": "2026-10-31T18:00:00.000Z"
}
}{
"error": {
"code": "COUPON_VALUE_INVALID",
"message": "Cupom percentual exige percentBp e não aceita amount."
}
}{
"error": {
"code": "INVALID_API_KEY",
"message": "Invalid or revoked API key"
}
}{
"error": {
"code": "INSUFFICIENT_SCOPE",
"message": "Required scope missing: balance:read"
}
}{
"error": {
"code": "COUPON_CODE_TAKEN",
"message": "Já existe um cupom com este código."
}
}Create a coupon
Create a discount coupon. Requires the coupons:write scope. Apply it with couponCode on POST /v1/payments, or let the payer type it on the hosted checkout. 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.
curl --request POST \
--url https://api.yuvexpay.com/v1/coupons \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"code": "black10",
"type": "PERCENT",
"percentBp": 1000,
"validFrom": "2026-11-27T00:00:00-03:00",
"validUntil": "2026-12-01T00:00:00-03:00",
"maxRedemptions": 500,
"maxRedemptionsPerBuyer": 1
}
'{
"coupon": {
"id": "4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e",
"code": "BLACK10",
"type": "PERCENT",
"percentBp": 1000,
"amount": null,
"validFrom": "2026-11-27T03:00:00.000Z",
"validUntil": "2026-12-01T03:00:00.000Z",
"maxRedemptions": 500,
"maxRedemptionsPerBuyer": 1,
"productIds": [],
"active": true,
"redemptionCount": 0,
"createdAt": "2026-10-31T18:00:00.000Z",
"updatedAt": "2026-10-31T18:00:00.000Z"
}
}{
"error": {
"code": "COUPON_VALUE_INVALID",
"message": "Cupom percentual exige percentBp e não aceita amount."
}
}{
"error": {
"code": "INVALID_API_KEY",
"message": "Invalid or revoked API key"
}
}{
"error": {
"code": "INSUFFICIENT_SCOPE",
"message": "Required scope missing: balance:read"
}
}{
"error": {
"code": "COUPON_CODE_TAKEN",
"message": "Já existe um cupom com este código."
}
}Authorizations
YuvexPay API key. Include as Authorization: Bearer ypk_<env>_<kid>_<secret> where <env> is test (sandbox) or live (production). Create and manage keys in the dashboard under Settings > API Keys.
Headers
Optional on this endpoint. When sent, a 2xx response is stored for 24 hours and replayed for a retry with the same key and body.
100Body
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).
PERCENT requires percentBp and FIXED requires amount; sending the other field, or neither, returns 400 COUPON_VALUE_INVALID.
PERCENT, FIXED PERCENT only: the discount in basis points, 1 to 10000 (10000 is 100%).
1 <= x <= 10000FIXED only: the discount in BRL, at most 2 decimal places.
x <= 1000000ISO 8601 date-time with an offset or Z. Inclusive.
ISO 8601 date-time with an offset or Z. Exclusive. Must be after validFrom (400 COUPON_WINDOW_INVALID).
Total uses, counting payments holding the coupon and completed ones. Omitted or null: no limit.
1 <= x <= 1000000Uses per payer e-mail, checked when the e-mail is known. Omitted or null: no limit.
1 <= x <= 1000000Products of your account in this environment that the discount covers (400 COUPON_PRODUCT_NOT_FOUND otherwise). Empty: the whole order.
100Response
Coupon created.
Show child attributes
Show child attributes