> ## Documentation Index
> Fetch the complete documentation index at: https://docs.momentco.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle

> Redemption statuses and state transitions

A redemption progresses through a series of states that describe its lifecycle, from creation through to a final outcome.

```mermaid theme={"system"}
stateDiagram-v2
    direction LR
    [*] --> draft: POST /redemptions
    draft --> reserved: if provider supports reservations
    draft --> confirmed: provider redeems stored value
    reserved --> confirmed: on confirm
    confirmed --> [*]
    reserved --> failed: release
    draft --> failed: on error
    failed --> [*]
```

* **`draft`**: `draft`: the redemption has been recorded but has not yet reached a final outcome.
* `confirmed`: the redemption completed successfully and the requested amount was redeemed from the provider's stored value. **The merchant is owed money.** `redeemed_amount` represents the amount redeemed.
* `failed`: the redemption could not be completed. The provider rejected the redemption (voucher already used, expired, invalid PIN, insufficient balance, etc.) or an error may have occurred. **No money has moved.** Additional information may be available in `last_error`.
* `reserved`: value has been reserved and is awaiting confirmation.

<Note>
  **Today, all supported providers complete redemption immediately.**\
  \
  **As a result, redemptions transition directly from** `draft `**to** `confirmed `**or** `failed`.\
  \
  See [`Providers`](/documentation/collect/redemptions/providers) for additional details.
</Note>

### How a redemption works

The lifecycle is consistent across stored value types. The examples below use voucher redemption, which is the stored value type supported today.\
\
The client makes a single API request. Moment manages the interaction with the underlying provider, including redemption processing, error handling, and recovery where supported.\
\
**Immediate Redemption**

For all currently supported providers, redemption is completed in a single request.

```mermaid theme={"system"}
sequenceDiagram
    autonumber
    participant C as Client
    participant R as Redemption Service
    participant P as Provider

    C->>R: POST /collect/redemptions
    Note over R: record redemption as `draft`<br/>emit `redemption.created`

    R->>P: redeem value
    P-->>R: response

    alt redemption accepted
        Note over R: state `draft` → `confirmed`<br/>emit `redemption.confirmed`
    else redemption rejected
        Note over R: state `draft` → `failed`<br/>emit `redemption.failed`
    end

    R-->>C: HTTP 201
```

**Reserved Redemption**

Some providers may support reserving value before final confirmation.

```mermaid theme={"system"}
sequenceDiagram
    autonumber
    participant C as Client
    participant R as Redemption Service
    participant P as Provider

    C->>R: POST /collect/redemptions

    R->>P: reserve value
    P-->>R: reserved

    Note over R: state `draft` → `reserved`<br/>emit `redemption.reserved`

    R-->>C: HTTP 201

    C->>R: POST /collect/redemptions/{id}/confirm

    R->>P: confirm redemption
    P-->>R: confirmed

    Note over R: state `reserved` → `confirmed`<br/>emit `redemption.confirmed`

    R-->>C: HTTP 200
```

### **Voucher Redemption Outcomes**

Voucher redemption may result in one of three outcomes.

1. **Full Redemption.** The requested amount is redeemed successfully and no value remains.
2. **Partial Redemption.** The requested amount is redeemed successfully and value remains after redemption. The remaining value may be returned as a replacement (change) voucher or delivered through another provider-specific mechanism. See Providers for more details.
3. **Failed Redemption.** The redemption is rejected and no value is redeemed. Common causes include invalid credentials, insufficient available value, expired vouchers, or previously redeemed vouchers.

### **Guarantees**

* **Duplicate Redemption Protection.** Repeated requests using the same `Idempotency-Key` return the original outcome without creating an additional redemption. Requests using the same key with different request bodies are rejected.
* **Remaining Value Preservation.** Where a provider returns remaining value after a partial redemption, that value is captured on the redemption and returned in the API response where supported.
* **Recovery from Ambiguous Provider Responses.** When a provider response times out, the service resolves the redemption to a final `confirmed` or `failed` state (never an indeterminate "maybe"), using provider-specific recovery endpoints where available.
* **Full Audit History.** Every redemption attempt, provider reference, state transition, and error is recorded on the redemption and remains available for auditing and troubleshooting.
* **Consistent Events.** Webhook events remain consistent with the redemption state, allowing downstream systems to process redemption outcomes reliably.