> ## Documentation Index > Fetch the complete documentation index at: https://docs.giftvoucherbrilliance.co.uk/llms.txt > Use this file to discover all available pages before exploring further. # Redeem a voucher > `redeem_vouchers` permission required. This operation changes voucher state. All successful responses include `X-Request-Id` and `Cache-Control: private, no-store`. Requests are limited to 120 per minute. ## OpenAPI ````yaml /openapi.json post /tenants/{tenant}/redemptions openapi: 3.1.0 info: title: Gift Voucher Brilliance External API version: 1.0.0 description: >- Read-only synchronisation and controlled voucher redemption for approved integrations. All operations require a bearer token. The API is limited to 120 requests per minute per token/IP combination. contact: name: Gift Voucher Brilliance Support url: https://docs.giftvoucherbrilliance.co.uk/support servers: - url: https://app.giftvoucherbrilliance.co.uk/api/external/v1 description: Production - url: https://app.gvb-staging.co.uk/api/external/v1 description: Staging - url: https://app.gvb.test/api/external/v1 description: Local security: - bearerAuth: [] tags: - name: Tenants description: Discover tenants available to the token. - name: Catalog description: Synchronise voucher products and categories. - name: Sales description: Synchronise purchased vouchers and balances. - name: Customers description: Export customers who opted in to marketing. - name: Redemptions description: Resolve, validate, and redeem vouchers. paths: /tenants/{tenant}/redemptions: post: tags: - Redemptions summary: Redeem a voucher description: >- `redeem_vouchers` permission required. This operation changes voucher state. All successful responses include `X-Request-Id` and `Cache-Control: private, no-store`. Requests are limited to 120 per minute. operationId: redeemVoucher parameters: - name: tenant in: path required: true description: Authorised tenant identifier from the tenant directory. schema: type: integer - name: Accept in: header required: true description: Must be `application/json`. schema: type: string enum: - application/json example: application/json requestBody: description: >- Use the short-lived token returned by resolve, or an authorised voucher id. Amount is in major units. required: true content: application/json: schema: allOf: - type: object properties: redemption_token: type: - string - 'null' voucher_id: type: - integer - 'null' minimum: 1 amount: type: - number - 'null' description: >- Optional partial redemption amount in major currency units. exclusiveMinimum: 0 - anyOf: - type: object properties: redemption_token: type: string required: - redemption_token - type: object properties: voucher_id: type: integer minimum: 1 required: - voucher_id responses: '200': description: Successful response. content: application/json: schema: $ref: '#/components/schemas/RedemptionResultItem' headers: X-Request-Id: description: Request correlation identifier. schema: type: string Cache-Control: description: Sensitive responses are not shared or stored. schema: type: string example: private, no-store '401': description: Unauthenticated or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/MessageError' '403': description: Token lacks the required tenant access or permission. content: application/json: schema: $ref: '#/components/schemas/MessageError' '404': description: Resource or tenant was not found in the authorised scope. content: application/json: schema: $ref: '#/components/schemas/MessageError' '422': description: Request validation failed. content: application/json: schema: $ref: '#/components/schemas/ValidationError' '429': description: Rate limit exceeded. Retry after the window resets. content: application/json: schema: $ref: '#/components/schemas/MessageError' components: schemas: RedemptionResultItem: type: object properties: data: $ref: '#/components/schemas/RedemptionResult' required: - data title: RedemptionResultItem MessageError: type: object properties: message: type: string required: - message title: MessageError ValidationError: type: object properties: message: type: string errors: type: object additionalProperties: type: array items: type: string required: - message - errors title: ValidationError RedemptionResult: type: object properties: status: type: string enum: - redeemed - failed reason_code: type: - string - 'null' enum: - void - already_redeemed - not_yet_active - expired - not_allowed_in_tenant - not_found - not_redeemable - null voucher: anyOf: - $ref: '#/components/schemas/RedemptionVoucher' - type: 'null' tenant: $ref: '#/components/schemas/RedemptionTenant' redeemed_at: type: - string - 'null' format: date-time description: ISO-8601 timestamp. actor: type: - object - 'null' properties: id: type: integer name: type: string required: - id - name required: - status - reason_code - voucher - tenant - redeemed_at - actor title: RedemptionResult RedemptionVoucher: type: object properties: id: type: integer reference: type: string product_title: type: - string - 'null' recipient_name: type: - string - 'null' customer_name: type: - string - 'null' current_balance: type: - integer - 'null' description: Amount in minor currency units (for example 2500 means £25.00). initial_balance: type: - integer - 'null' description: Amount in minor currency units (for example 2500 means £25.00). currency: type: string is_monetary: type: boolean allow_part_redeem: type: boolean redemption_status: type: string void: type: boolean date_valid_start: type: - string - 'null' format: date description: ISO-8601 calendar date. date_valid_end: type: - string - 'null' format: date description: ISO-8601 calendar date. status: type: string enum: - redeemable - blocked reason_code: type: - string - 'null' enum: - void - already_redeemed - not_yet_active - expired - null required: - id - reference - current_balance - initial_balance - currency - is_monetary - allow_part_redeem - status - reason_code title: RedemptionVoucher RedemptionTenant: type: object properties: id: type: integer name: type: string type: type: string source_tenant_id: type: integer source_tenant_name: type: string source_tenant_type: type: string required: - id - name - type - source_tenant_id - source_tenant_name - source_tenant_type title: RedemptionTenant securitySchemes: bearerAuth: type: http description: Bearer token created in the GVB API Access page. scheme: bearer ````