> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retempo.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Status Reference for Services, Invoices, and Settlements
> Complete reference for all status values across Retempo entities — services, payment plans, checkout sessions, subscriptions, invoices, and settlements.
Retempo uses status fields to track the lifecycle of each entity. As your services run, subscriptions activate, and settlements confirm on Arc, these statuses update automatically to reflect the current state. Use this reference to understand what each status means, when it appears, and what transitions to expect.
## Services
A service moves through three statuses from creation to retirement. When you first create a service, it starts in `DRAFT` and does not accept any checkout sessions until you activate it.
| Status | Meaning |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DRAFT` | The service has been created but is not yet live. No checkout sessions can be opened against it. Use this state to configure payment plans before going live. |
| `ACTIVE` | The service is live and accepting checkout sessions. Subscribers can initiate and complete payments against any of its active payment plans. |
| `DISABLED` | The service no longer accepts new subscriptions or checkout sessions. Existing active subscriptions continue until they expire or are cancelled. |
Transitioning a service from `ACTIVE` back to `DRAFT` is not supported. To stop accepting new subscriptions, set the service status to `DISABLED`.
## Payment Plans
Payment plans define how and when subscribers are billed. The pricing type and billing interval together determine the billing behavior for each plan.
### Pricing Types
| Pricing Type | Meaning |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- |
| `FIXED_RECURRING` | The same USDC amount is billed at every billing interval. Use this for flat-rate subscriptions. |
| `USAGE_BASED` | The billed amount is calculated from recorded usage events during the interval. The final amount varies each cycle. |
| `ONE_TIME` | A single charge with no recurring billing. Set `billingInterval` to `NONE` when using this type. |
### Billing Intervals
| Billing Interval | Meaning |
| ---------------- | ----------------------------------------------------------------------------------------- |
| `MONTH` | The subscriber is billed once per calendar month. |
| `WEEK` | The subscriber is billed once per week. |
| `DAY` | The subscriber is billed once per day. |
| `NONE` | No automatic recurring schedule. Use this for manual billing or `ONE_TIME` pricing plans. |
## Checkout Sessions
A checkout session represents a subscriber's in-progress payment flow. Sessions are time-limited and transition to a terminal status once the subscriber pays, the session expires, or you cancel it.
| Status | Meaning |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PENDING` | The session has been created and is waiting for the subscriber to complete payment. The session URL is active and the subscriber can proceed. |
| `PAID` | The subscriber completed payment and the session has been processed. The associated subscription is now activated. This is a terminal status. |
| `EXPIRED` | The session window closed before the subscriber completed payment. The subscriber must initiate a new checkout session. This is a terminal status. |
| `CANCELLED` | You or the system cancelled the session before payment was completed. The subscriber must initiate a new checkout session. This is a terminal status. |
Set an appropriate `expiresAt` on your checkout sessions to control how long a payment link stays valid. Expired sessions cannot be reactivated.
## Subscriptions
A subscription tracks an active recurring billing relationship with a subscriber. It activates automatically when a checkout session transitions to `PAID` and continues through each billing cycle until it is cancelled or expires.
| Status | Meaning |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `ACTIVE` | The subscription is current. Invoices are being generated and settled on schedule. |
| `PAST_DUE` | A payment cycle has passed without a confirmed settlement. The subscription remains open but action is needed to resolve the overdue invoice. |
| `CANCELLED` | The subscription has been cancelled by you or the subscriber. No further invoices will be generated. This is a terminal status. |
| `EXPIRED` | The subscription's billing period has ended naturally. No further invoices will be generated. This is a terminal status. |
A subscription in `PAST_DUE` state will not automatically recover. You must resolve the overdue invoice — either by recording a successful settlement or voiding the invoice — before the subscription resumes normal billing.
## Invoices
An invoice represents a single billing event within a subscription cycle. Retempo generates invoices automatically at each billing interval and advances them through the following statuses as payment is collected and confirmed.
| Status | Meaning |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `DRAFT` | The invoice has been created but not yet finalized. Amounts or details may still be adjusted at this stage. |
| `OPEN` | The invoice has been finalized and payment is due. A settlement is expected to close this invoice. |
| `PAID` | Payment has been confirmed via a completed settlement. This is a terminal status. |
| `VOID` | The invoice has been cancelled and will not be collected. Use this to write off an invoice that should not be paid. This is a terminal status. |
| `EXPIRED` | The invoice passed its due date without a confirmed payment. This is a terminal status. |
Invoices are marked `PAID` only after a settlement is `CONFIRMED` on Arc. This transition is automatic — you do not need to manually update the invoice status after submitting a settlement.
## Settlements
A settlement tracks the on-chain USDC transfer that closes an invoice. Retempo submits settlements to Arc and monitors the resulting transaction to confirm or flag failure.
| Status | Meaning |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `PENDING` | The settlement record has been created in Retempo but has not yet been submitted to Arc. It is queued for on-chain submission. |
| `SUBMITTED` | The settlement has been submitted to Arc and is awaiting an on-chain receipt. The transaction is in-flight. |
| `CONFIRMED` | Arc returned a receipt and the `SettlementRecorded` event was observed on-chain. The associated invoice is automatically marked `PAID`. This is a terminal status. |
| `FAILED` | The Arc transaction failed or the expected on-chain event was not observed. The settlement did not complete. You can investigate and resubmit. |
A `FAILED` settlement does not automatically retry. Check the transaction details on Arc, verify your payer and merchant addresses, and submit a new settlement to reattempt payment.