Kaiten

Redeem a voucher

Redeems a voucher for an instance. A boost applies from the next read or report, for its duration; a PRICE voucher discounts the subscription's next invoices. 422 .DiscountLimitExceeded when a line of the instance's invoices would bear more than 20 discounts, whatever the provider (a Stripe invoice item takes 20). Emits INSTANCE_VOUCHER_REDEEMED, and VOUCHER_EXHAUSTED with the last redemption. Requires billing to be enabled for the organization.

POST
/instances/{instanceSlug}/vouchers/redeem

Authorization

bearerAuth write:voucher_redemptions
AuthorizationBearer <token>

A JWT verified by the proxy in front of this API, or a Kaiten access token (ksh_...) — send either as Authorization: Bearer <token>. The scopes listed on each operation are checked server-side against current stored user assignments or stored service-token permissions, never JWT claims; write:<module> implies read:<module>, and read:* / write:* are wildcards over every module. x-kaiten-scopes lists every scope such a token can carry, including those enforced by a service in front of this API rather than by one of its operations.

In: header

Scope: write:voucher_redemptions

Path Parameters

instanceSlug*string

Instance slug

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://app.kaiten.sh/api/instances/acme-prod/vouchers/redeem" \  -H "Content-Type: application/json" \  -d '{    "code": "SUMMER-2026-LAUNCH"  }'
{
  "applicationsCount": 0,
  "applicationsMax": 0,
  "codeHint": "string",
  "effectiveExpiresAt": "2019-08-24T14:15:22Z",
  "effectiveStartsAt": "2019-08-24T14:15:22Z",
  "expiredAt": "2019-08-24T14:15:22Z",
  "id": "string",
  "instanceSlug": "string",
  "redeemedAt": "2019-08-24T14:15:22Z",
  "revokedAt": "2019-08-24T14:15:22Z",
  "revokedReason": "string",
  "status": "ACTIVE",
  "voucherId": "string",
  "voucherName": "string",
  "voucherType": "PRICE"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}

List an instance's vouchers

The vouchers an instance redeemed, newest first. Requires billing to be enabled for the organization.

Revoke a redemption

Stops a redemption from applying: a boost ends at once, a discount applies to no further invoice. Invoices already issued are untouched. Emits INSTANCE_VOUCHER_REVOKED. Requires billing to be enabled for the organization.