---
title: "Redeem Receipt"
method: POST
path: "/v1/receipts/{orderNumber}/redeem"
tags: ["Receipt"]
---

# Redeem Receipt

`POST /v1/receipts/{orderNumber}/redeem`

Redeem one or more entitlements from a receipt. When processing a bulk redemption, if any entitlement is already exhausted, the entire operation is rejected.

## Path parameters

- `orderNumber` string, required — The order number of the receipt to be redeemed.

## Headers

- `Idempotency-Key` string, required — This header is used to uniquely identify a logical request, ensuring that it is not processed more than once during retries.
- `Monime-Version` 'caph.2025-08-23' | 'caph.2025-06-20', nullable — Specifies which version of the Monime API will handle this request.
- `Monime-Space-Id` string, required — The value is the tenancy parameter that Monime uses to determine which space the request is intended for.

## Request body

- object — Redeem one or more entitlements from a receipt. When processing a bulk redemption, if any entitlement is already exhausted, the entire operation is rejected.
  - `redeemAll` boolean, nullable — Whether to redeem all entitlements in the receipt.
  - `entitlements` object[], nullable — List of entitlements to redeem. When set, it takes precedence over the 'redeemAll' flag.
    - `key` string, required — Stable entitlement key (e.g., SKU, ticket_type, or any identifier unique to the product).
    - `units` integer — Units of entitlement to redeem. This should not exceed the remaining quantity of the entitlement.
  - `metadata` object, nullable — Optional metadata for attaching context or tracking info.

## Response `200`

OK

- object
  - `success` boolean — Represents the status of the query operation, confirming if it was successful. This field is always true
  - `messages` unknown[] — Contains a list of messages providing relevant information or feedback related to the query or operation
    - unknown
  - `result` object — Represents the outcome of redeeming entitlement(s) from a receipt.
    - `redeem` boolean — Whether the redemption was successful. This will be false if any of the entitlements had already been exhausted.
    - `receipt` Receipt — A **Receipt** is a record of entitlements generated by Monime whenever a payment completes successfully. It serves as proof of what the customer is entitled to claim — such as tickets, vouchers, credits, or digital rights. Receipt links a **payment** via an order to **entitlement claims**, enabling both verification and controlled redemption via APIs. ### Use Cases - **Purchase Verification** Confirm that a customer’s payment went through and display transaction details in your app without manual reconciliation. - **Ticket & Voucher Redemption** Use receipts as redeemable proof of access — for example, scanning a receipt at an event gate or validating a voucher at checkout. - **Partial Consumption** Support use cases where receipts hold multiple entitlements, such as ride credits or digital assets, and allow them to be redeemed incrementally.
      - `status` 'not_redeemed' | 'partially_redeemed' | 'fully_redeemed' — Lifecycle status of the receipt.
      - `orderName` string, nullable — Human friendly name of the order.
      - `orderNumber` string — Human-friendly order number.
      - `orderAmount` object — Total order amount in minor units and currency.
        - `currency` string — The [3-letter](https://en.wikipedia.org/wiki/ISO_4217) ISO currency code. Currently supported: 'SLE', 'USD'
        - `value` integer — The value representation in the currency's minor unit. E.g. For 1 Leone (SLE 1), the value should be 100, denoting cents, the minor unit.
      - `createTime` string, date-time — The timestamp when the receipt was created.
      - `updateTime` string, date-time — The last timestamp when the receipt was updated.
      - `entitlements` object[], nullable — Entitlements granted by this receipt; each can be redeemed until exhausted.
        - `key` string — Stable entitlement key (e.g., SKU, ticket_type, or any unique product identifier).
        - `name` string, nullable — Human-friendly name of the entitlement.
        - `limit` integer — Maximum number of times this entitlement can be redeemed.
        - `current` integer — Number of times this entitlement has been redeemed so far.
        - `remaining` integer — Number of redemptions still available (limit - current).
        - `exhausted` boolean — True if the entitlement has no remaining redemptions (i.e. current == limit).
      - `metadata` object, nullable — Optional metadata for attaching context or tracking info.

---

[API](https://skmtc.dev/monime/apis/monime-api.md) · [All operations](https://skmtc.dev/monime/apis/monime-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/monime/monime-api/revisions/bd7f875ea428/schema)