> ## 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. # Update a coupon > Update one or more fields of a coupon. Requires the `coupons:write` scope. The change applies from the next time the coupon is applied; a payment that already holds the coupon keeps it. ## OpenAPI ````yaml PATCH /v1/coupons/{couponId} 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/{couponId}: patch: tags: - Coupons summary: Update a coupon description: >- Update one or more fields of a coupon. Requires the `coupons:write` scope. The change applies from the next time the coupon is applied; a payment that already holds the coupon keeps it. operationId: updateCoupon parameters: - name: couponId in: path required: true schema: type: string format: uuid description: The coupon ID. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateCouponRequest' example: active: false responses: '200': description: Coupon updated. content: application/json: schema: type: object properties: coupon: $ref: '#/components/schemas/Coupon' required: - coupon '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' '404': $ref: '#/components/responses/NotFound' '409': description: >- `COUPON_CODE_TAKEN`: another coupon of your account in this environment that is not deleted has this code. 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: UpdateCouponRequest: type: object description: >- Send only the fields to change. `null` clears a nullable field. Changing `type` without the value of the new type returns `400 COUPON_VALUE_INVALID`, since the value of the old type is cleared. 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 percentBp: type: - integer - 'null' minimum: 1 maximum: 10000 amount: type: - number - 'null' exclusiveMinimum: 0 maximum: 1000000 validFrom: type: - string - 'null' format: date-time validUntil: type: - string - 'null' format: date-time maxRedemptions: type: - integer - 'null' minimum: 1 maximum: 1000000 maxRedemptionsPerBuyer: type: - integer - 'null' minimum: 1 maximum: 1000000 productIds: type: array maxItems: 100 items: type: string format: uuid description: Replaces the whole list. active: type: boolean 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' NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Resource not found 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.