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

# Lifecycle and Statuses

> What each status means and which operations change it

Every agentic resource reports a `status`. This page maps each value to the action it calls for, and covers the operations that move a resource from one value to the next.

## Enrollment

```mermaid theme={null}
stateDiagram-v2
    [*] --> REQUIRES_ACTION: create enrollment
    REQUIRES_ACTION --> ACTIVE: user completes the hosted step
    ACTIVE --> REVOKED: revoke enrollment
    REVOKED --> [*]
```

| Status | What it means | What to do |
| - | - | - |
| `REQUIRES_ACTION` | A hosted step is outstanding | Send the user to `nextAction.url` before `expiresAt`, then read the enrollment again |
| `ACTIVE` | The card is stored and ready | Use the enrollment ID at checkout |
| `REVOKED` | The stored card no longer accepts charges | Create a new enrollment for a replacement card |
| `FAILED` | Reap could not store the card | Create a new enrollment and send the user through the hosted step again |
| `EXPIRED` | The user did not finish the hosted step before `expiresAt` | Create a new enrollment and send the user to the new `nextAction.url` |

External cards require hosted card entry. Follow `nextAction.url` and read the enrollment again to confirm `ACTIVE`. Show your terms of service and privacy policy before you store the card, as [Consent and terms](https://docs.reap.global/agentic-payments/how-it-works.md#consent-and-terms) describes.

### Revoke an enrollment

Revoke a stored card with [`POST /agentic/enrollments/:id/revoke`](https://docs.reap.global/api-reference/agentic/revoke-enrollment) when the user removes it or when the card should stop working.

```json Response (relevant fields) theme={null}
{
  "id": "<enrollment-id>",
  "status": "REVOKED"
}
```

See the [revoke enrollment reference](https://docs.reap.global/api-reference/agentic/revoke-enrollment.md) for the full response.

Only an `ACTIVE` enrollment can be revoked. Any other status returns `ENROLLMENT_NOT_ACTIVE`.

> [!WARNING]
>
> Revoking is final. You cannot charge or restore a revoked enrollment. You will need to create a new enrollment to use the same card.

## Mandate

```mermaid theme={null}
stateDiagram-v2
    [*] --> REQUIRES_ACTION: create mandate
    REQUIRES_ACTION --> ACTIVE: user approves the mandate
    REQUIRES_ACTION --> EXPIRED: no approval before expiresAt
    REQUIRES_ACTION --> FAILED: the mandate could not be set up
    ACTIVE --> PAUSED: pause
    PAUSED --> ACTIVE: resume
    ACTIVE --> CONSUMED: the budget is used up
    ACTIVE --> CANCELLED: cancel
    PAUSED --> CANCELLED: cancel
    ACTIVE --> REVOKED: revoke the enrollment
    PAUSED --> REVOKED: revoke the enrollment
    CONSUMED --> [*]
    CANCELLED --> [*]
    REVOKED --> [*]
    EXPIRED --> [*]
    FAILED --> [*]
```

| Status | What it means | What to do |
| - | - | - |
| `REQUIRES_ACTION` | The mandate is not approved yet | Show your terms of service and privacy policy, then complete the step in `nextAction` and read the mandate again |
| `ACTIVE` | Charges can run under the approved mandate | Charge within `amount` and `frequency`, at the `merchant` on the mandate |
| `PAUSED` | Charges are on hold and the mandate is intact | Resume the mandate to continue |
| `CONSUMED` | A `ONE_TIME` mandate has no budget left, because `usage.spent` plus `usage.pending` equals `amount` | Collect a new mandate from the user |
| `CANCELLED` | You ended the mandate and the stored card stays usable | Collect a new mandate from the user |
| `REVOKED` | The enrollment behind the mandate was revoked | Create a new enrollment, then collect a new mandate |
| `EXPIRED` | The user did not approve before `nextAction.expiresAt` | Collect a new mandate from the user |
| `FAILED` | Reap could not set up the mandate | Collect a new mandate from the user |

`CANCELLED` and `REVOKED` are both end states, and neither returns to `ACTIVE`. The difference is scope. Canceling ends one mandate and leaves the stored card ready for a new one. Revoking the enrollment stops every mandate that points at that card. `CONSUMED`, `EXPIRED`, and `FAILED` are also final, and each one calls for a new mandate.

Reap works out `CONSUMED` each time you read the mandate. A charge that is still in progress already counts against the budget, so the mandate can read `CONSUMED` before its last checkout completes. When the mandate was also canceled, revoked, or has expired, you see that status instead.

### List mandates

[`GET /agentic/mandates`](https://docs.reap.global/api-reference/agentic/list-mandates) lists the mandates of one owner. `ownerId` is required, because every list is scoped to a single owner, and `ownerType` defaults to `CLIENT_REFERENCE`. Narrow the list with `enrollmentId`, or with `status`, a comma-separated list that defaults to `ACTIVE`. Pass `ACTIVE,PAUSED` to include paused mandates.

```json Response (relevant fields) theme={null}
{
  "items": [
    {
      "id": "<mandate-id>",
      "status": "ACTIVE",
      "usage": { "spent": 300, "pending": 0, "cycle": { "renewsAt": "2026-01-08T00:00:00Z" } }
    }
  ],
  "nextCursor": null
}
```

See the [list mandates reference](https://docs.reap.global/api-reference/agentic/list-mandates.md) for the full response.

Follow `nextCursor` when it holds a value. A `null` cursor means the last page.

### Pause a mandate

[`POST /agentic/mandates/:id/pause`](https://docs.reap.global/api-reference/agentic/pause-mandate) holds charges and keeps the approved mandate.

```json Response (relevant fields) theme={null}
{
  "id": "<mandate-id>",
  "status": "PAUSED"
}
```

See the [pause mandate reference](https://docs.reap.global/api-reference/agentic/pause-mandate.md) for the full response.

### Resume a mandate

[`POST /agentic/mandates/:id/resume`](https://docs.reap.global/api-reference/agentic/resume-mandate) returns `status` as `ACTIVE` with the same mandate. Resuming needs no further approval from the user, because nothing about the mandate changed.

```json Response (relevant fields) theme={null}
{
  "id": "<mandate-id>",
  "status": "ACTIVE"
}
```

See the [resume mandate reference](https://docs.reap.global/api-reference/agentic/resume-mandate.md) for the full response.

### Cancel a mandate

[`POST /agentic/mandates/:id/cancel`](https://docs.reap.global/api-reference/agentic/cancel-mandate) returns `status` as `CANCELLED`. The enrollment stays untouched and remains available for a new purchase.

```json Response (relevant fields) theme={null}
{
  "id": "<mandate-id>",
  "status": "CANCELLED"
}
```

See the [cancel mandate reference](https://docs.reap.global/api-reference/agentic/cancel-mandate.md) for the full response.

Pause and resume suit a temporary hold. Cancel ends the mandate for good. Revoking the enrollment is the wider action, because it stops charges across every mandate that points at the same stored card, and those mandates report `REVOKED` rather than `CANCELLED`.

## Quote

A quote has no status field. It has an expiry instead.

* Read `expiresAt` on every quote and open the checkout before that time
* Create a new quote with [`POST /agentic/quotes`](https://docs.reap.global/api-reference/agentic/create-quote) once the expiry has passed, because merchant prices can move in between
* Read the quote at any time with [`GET /agentic/quotes/:id`](https://docs.reap.global/api-reference/agentic/get-quote) to get the current total

A call that reaches an expired quote returns `QUOTE_EXPIRED`, and a shipping option change that the merchant can no longer apply returns `QUOTE_REPLACEMENT_REQUIRED`. Both mean the same thing: create a new quote.

## Checkout

```mermaid theme={null}
stateDiagram-v2
    [*] --> REQUIRES_ACTION: create checkout
    [*] --> PROCESSING: create checkout under an approved mandate
    REQUIRES_ACTION --> PROCESSING: user approves the charge
    REQUIRES_ACTION --> EXPIRED: no approval before expiresAt
    PROCESSING --> COMPLETED: the merchant places the order
    PROCESSING --> FAILED: the charge or the order does not go through
    COMPLETED --> [*]
    FAILED --> [*]
    EXPIRED --> [*]
```

| Status | What it means | What to do |
| - | - | - |
| `REQUIRES_ACTION` | The charge is waiting on user approval | Show your terms of service and privacy policy, then send the user to `nextAction.url` before `expiresAt` |
| `PROCESSING` | The charge is approved and the order is being placed | Read the checkout again until it reports a final status |
| `COMPLETED` | The merchant order is placed | Store `orderId` and reconcile against `finalAmount` |
| `FAILED` | The charge or the merchant order did not go through | Read `failureReason` to see why, tell the user the purchase did not happen, then create a new quote and a new checkout |
| `EXPIRED` | The user did not approve before `expiresAt` | Create a new quote and a new checkout, because the old quote is stale |

`COMPLETED`, `FAILED`, and `EXPIRED` are final. A checkout never leaves one of them, so branch on the status value rather than treating anything other than `COMPLETED` as still in flight. Neither `FAILED` nor `EXPIRED` can be retried in place, and both need a fresh quote and a fresh checkout.

[`POST /agentic/checkouts`](https://docs.reap.global/api-reference/agentic/create-checkout) returns a `nextAction` when the charge needs approval. A checkout created under a mandate the user approved earlier skips that step and moves straight into `PROCESSING`. Whenever the user has to approve, show your terms of service and privacy policy first, whatever surface the user approves from. [Consent and terms](https://docs.reap.global/agentic-payments/how-it-works.md#consent-and-terms) covers the rule.

A checkout paid through a mandate carries its `mandateId`, and a hosted checkout returns `null` there. A failed checkout carries `failureReason` with a `code` and a `message`.

Read the checkout with [`GET /agentic/checkouts/:id`](https://docs.reap.global/api-reference/agentic/get-checkout) after the user lands back on your return URL. Returning to that URL does not by itself mean the order is placed, so read the status. A `nextAction` of `null` on a completed checkout means you have nothing left to do.

## Status change events

Reap sends a [webhook](https://docs.reap.global/webhooks/overview.md) when an enrollment or a checkout reaches one of the statuses below, so you learn the outcome of a hosted step without reading the resource again. The `data` of each event matches the response of the matching `GET` endpoint.

| Event | Sent when |
| - | - |
| [`AGENTIC_ENROLLMENT_UPDATED`](https://docs.reap.global/api-reference/agentic-enrollment-updated) | An enrollment becomes `ACTIVE`, `FAILED`, `EXPIRED`, or `REVOKED` |
| [`AGENTIC_CHECKOUT_UPDATED`](https://docs.reap.global/api-reference/agentic-checkout-updated) | A checkout becomes `COMPLETED` or `EXPIRED` |

> [!NOTE]
>
> A checkout that ends in `FAILED` sends no event. While a checkout reports `PROCESSING`, read it again with [`GET /agentic/checkouts/:id`](https://docs.reap.global/api-reference/agentic/get-checkout) until it reports a final status or the webhook arrives.

## Next steps

> [card] [One-Time Purchases](https://docs.reap.global/agentic-payments/one-time-purchases.md)
>
> The full purchase sequence with requests and responses.

> [card] [FAQ](https://docs.reap.global/agentic-payments/faq.md)
>
> Short answers to common integration questions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.