> ## Documentation Index > Fetch the complete documentation index at: https://docs.yuvexpay.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml POST /v1/coupons openapi: 3.1.0 info: title: YuvexPay API description: >- The YuvexPay API allows you to accept payments, process withdrawals, manage products, coupons and customers programmatically. All API access is over HTTPS and uses JSON request/response bodies. version: 1.0.0 contact: name: YuvexPay Support email: support@yuvexpay.com url: https://docs.yuvexpay.com servers: - url: https://api.yuvexpay.com description: >- Same base URL serves both sandbox and production. Send a `ypk_test_*` key for sandbox or a `ypk_live_*` key for production. security: - bearerAuth: [] tags: - name: Authentication description: Inspect the API key in use - name: Payments description: Create and manage payments - name: Withdrawals description: Create and manage withdrawals - name: Products description: Manage product catalog - name: Customers description: Manage customer records - name: Coupons description: Manage discount coupons - name: Documents description: Generate receipts and statements - name: Balance description: Inspect the current account balance - name: Splits description: Inspect the split partners of the account - name: Public description: Public information that needs no API key paths: /v1/coupons: post: tags: - Coupons summary: Create a coupon description: >- 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. operationId: createCoupon parameters: - name: X-Idempotency-Key in: header required: false schema: type: string maxLength: 100 description: >- 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. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCouponRequest' examples: percent: summary: 10% off the whole order, one use per payer value: 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 fixed: summary: R$ 20.00 off one product value: code: BONE20 type: FIXED amount: 20 productIds: - 8a3f1c2e-6b4d-4e7a-9c1b-2d3e4f5a6b7c responses: '201': description: Coupon created. content: application/json: schema: type: object properties: coupon: $ref: '#/components/schemas/Coupon' required: - coupon example: 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' '400': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/Error' examples: couponValueInvalid: summary: '`amount` sent on a `PERCENT` coupon' value: error: code: COUPON_VALUE_INVALID message: Cupom percentual exige percentBp e não aceita amount. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': description: >- `COUPON_CODE_TAKEN`: another coupon of your account in this environment that is not deleted has this code. A reused `X-Idempotency-Key` returns the flat idempotency errors instead. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: COUPON_CODE_TAKEN message: Já existe um cupom com este código. components: schemas: CreateCouponRequest: type: object properties: code: type: string description: >- 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: type: string enum: - PERCENT - FIXED description: >- `PERCENT` requires `percentBp` and `FIXED` requires `amount`; sending the other field, or neither, returns `400 COUPON_VALUE_INVALID`. percentBp: type: integer minimum: 1 maximum: 10000 description: >- `PERCENT` only: the discount in basis points, `1` to `10000` (`10000` is 100%). amount: type: number exclusiveMinimum: 0 maximum: 1000000 description: '`FIXED` only: the discount in BRL, at most 2 decimal places.' validFrom: type: - string - 'null' format: date-time description: ISO 8601 date-time with an offset or `Z`. Inclusive. validUntil: type: - string - 'null' format: date-time description: >- ISO 8601 date-time with an offset or `Z`. Exclusive. Must be after `validFrom` (`400 COUPON_WINDOW_INVALID`). maxRedemptions: type: - integer - 'null' minimum: 1 maximum: 1000000 description: >- Total uses, counting payments holding the coupon and completed ones. Omitted or `null`: no limit. maxRedemptionsPerBuyer: type: - integer - 'null' minimum: 1 maximum: 1000000 description: >- Uses per payer e-mail, checked when the e-mail is known. Omitted or `null`: no limit. productIds: type: array maxItems: 100 default: [] items: type: string format: uuid description: >- Products of your account in this environment that the discount covers (`400 COUPON_PRODUCT_NOT_FOUND` otherwise). Empty: the whole order. active: type: boolean default: true required: - code - type Coupon: type: object properties: id: type: string format: uuid code: type: string description: Uppercase code, 3 to 32 characters from `A-Z`, `0-9`, `_` and `-`. example: BLACK10 type: type: string enum: - PERCENT - FIXED percentBp: type: - integer - 'null' minimum: 1 maximum: 10000 description: >- `PERCENT` only: the discount in basis points, `1500` for 15% and `10000` for 100%. `null` on a `FIXED` coupon. amount: type: - number - 'null' description: '`FIXED` only: the discount in BRL. `null` on a `PERCENT` coupon.' validFrom: type: - string - 'null' format: date-time description: 'The coupon works from this time on, inclusive. `null`: no start.' validUntil: type: - string - 'null' format: date-time description: 'The coupon stops working at this time, exclusive. `null`: no end.' maxRedemptions: type: - integer - 'null' minimum: 1 description: 'Total uses. `null`: no limit.' maxRedemptionsPerBuyer: type: - integer - 'null' minimum: 1 description: 'Uses per payer e-mail. `null`: no limit.' productIds: type: array items: type: string format: uuid description: 'Products the discount covers. Empty: the whole order.' active: type: boolean redemptionCount: type: integer minimum: 0 description: >- 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: type: string format: date-time updatedAt: type: string format: date-time required: - id - code - type - percentBp - amount - validFrom - validUntil - maxRedemptions - maxRedemptionsPerBuyer - productIds - active - redemptionCount - createdAt - updatedAt Error: type: object properties: error: type: object properties: code: type: string description: Machine-readable error code. message: type: string description: Human-readable error message. details: type: object description: Additional error context. responses: Unauthorized: description: Missing or invalid authentication token. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_API_KEY message: Invalid or revoked API key Forbidden: description: >- The API key is valid but does not have the required scope for this endpoint. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INSUFFICIENT_SCOPE message: 'Required scope missing: balance:read' securitySchemes: bearerAuth: type: http scheme: bearer description: >- YuvexPay API key. Include as `Authorization: Bearer ypk___` where `` is `test` (sandbox) or `live` (production). Create and manage keys in the dashboard under **Settings > API Keys**. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.