YUyuvexpay
Coupons

Create a coupon

Changed on

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.

post/v1/coupons

Request

Headers

X-Idempotency-Keystring

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.

Request body

codestring required

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' required

PERCENT requires percentBp and FIXED requires amount; sending the other field, or neither, returns 400 COUPON_VALUE_INVALID.

percentBpinteger

PERCENT only: the discount in basis points, 1 to 10000 (10000 is 100%).

amountnumber

FIXED only: the discount in BRL, at most 2 decimal places.

validFromstring date-time nullable

ISO 8601 date-time with an offset or Z. Inclusive.

validUntilstring date-time nullable

ISO 8601 date-time with an offset or Z. Exclusive. Must be after validFrom (400 COUPON_WINDOW_INVALID).

maxRedemptionsinteger nullable

Total uses, counting payments holding the coupon and completed ones. Omitted or null: no limit.

maxRedemptionsPerBuyerinteger nullable

Uses per payer e-mail, checked when the e-mail is known. Omitted or null: no limit.

productIdsstring[]

Products of your account in this environment that the discount covers (400 COUPON_PRODUCT_NOT_FOUND otherwise). Empty: the whole order.

activeboolean

Response

Coupon created.

Example response

{
  "coupon": {
    "code": "BLACK10"
  }
}

Changes