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.