Retempo’s data model is built around seven core entities that work together to take a payment from first configuration to onchain confirmation. Understanding how these entities relate to each other will help you design integrations that are predictable, auditable, and easy to maintain.
Retempo does not manage custody, balances, refunds, or KYC. It is a settlement orchestration and proof layer.
Service
A service represents something you sell — an API, a SaaS tool, an AI agent capability, or any other product you want to monetize with recurring USDC payments.
Every service has a name, an optional description, and an owner (the developer or organization selling it). The status field controls whether the service is available for new subscriptions:
| Status | Meaning |
|---|
DRAFT | The service is being configured and is not yet visible to subscribers. |
ACTIVE | The service is live. Subscribers can complete checkout sessions against it. |
DISABLED | The service is no longer accepting new subscribers. Existing subscriptions are unaffected. |
ACTIVE status before you can use it in a checkout session.
Payment Plan
A payment plan defines the price and billing cadence attached to a service. Every checkout session and invoice references a specific payment plan, so you can offer multiple pricing tiers on a single service.
Pricing types control how the amount is calculated:
pricingType | Meaning |
|---|
FIXED_RECURRING | The same USDC amount is charged every billing interval. |
USAGE_BASED | The amount is calculated from usage events recorded during the billing period. |
ONE_TIME | A single USDC charge with no recurring component. |
billingInterval | Meaning |
|---|
MONTH | Charged once per calendar month. |
WEEK | Charged once per week. |
DAY | Charged once per day. |
NONE | No recurring interval — used with ONE_TIME pricing. |
Checkout Session
A checkout session is a temporary, subscriber-facing session that takes someone through the payment flow for a specific service and payment plan. You create a checkout session via the API and receive a session id you can use to route your subscriber to the checkout page at https://retempo.xyz.
Checkout sessions move through the following statuses:
| Status | Meaning |
|---|
PENDING | The session is open and waiting for the subscriber to complete payment. |
PAID | The subscriber completed payment. A subscription has been created. |
EXPIRED | The session was not completed before its expiry time. |
CANCELLED | The session was cancelled before completion. |
PAID, Retempo automatically creates a Subscription to track the ongoing billing relationship.
Subscription
A subscription is created automatically when a checkout session is completed. It represents the active billing relationship between a subscriber and your service, and it ties together the service, the payment plan, and the subscriber identity.
Retempo uses the subscription record to determine when to generate invoices for recurring plans. You do not need to create subscriptions directly — they are always the result of a completed checkout session.
Usage Event
A usage event records a single metered action that contributes to a USAGE_BASED invoice. Each event carries an eventKey (a string that identifies the type of action, such as "api_call" or "tokens_generated") and a quantity (how many units occurred).
Usage events are tied to a subscription and, once an invoice is open, can be associated with a specific invoice. At billing time, Retempo aggregates the quantity across all events for the period and calculates the invoice amount according to the plan’s pricing rules.
Use descriptive, stable eventKey values — changing them mid-billing-period can cause usage to be attributed to the wrong rate or not aggregated correctly.
Invoice
An invoice is the billing record for a subscription cycle. It captures the amount owed, the service and plan it relates to, the subscriber, and the current payment status.
Invoices move through the following lifecycle:
| Status | Meaning |
|---|
DRAFT | The invoice is being prepared and has not yet been sent or opened for payment. |
OPEN | The invoice is ready for settlement. |
PAID | The invoice has been settled. This status is only set after a linked settlement reaches CONFIRMED. |
VOID | The invoice was cancelled and will not be collected. |
EXPIRED | The invoice was not paid within the allowed window. |
PAID by a manual API call. It transitions to PAID only after Retempo confirms the linked settlement onchain.
Settlement
A settlement is the onchain proof that a payment occurred. When you submit a settlement, Retempo sends a transaction to Arc (Chain ID 5042002). Arc records the payment and Retempo confirms the receipt before marking the settlement complete.
Settlements move through the following statuses:
| Status | Meaning |
|---|
PENDING | The settlement has been created and is queued for submission to Arc. |
SUBMITTED | The transaction has been sent to Arc and is awaiting block confirmation. |
CONFIRMED | Arc confirmed the transaction. The linked invoice is now marked PAID. |
FAILED | The transaction failed or was rejected. The invoice remains OPEN. |
transactionHash — the Arc transaction hash that proves the settlement onchain.referenceHash — a 32-byte hex value you provide that links the Arc record back to your internal payment reference.
Because settlement confirmation is driven by real onchain events, there is no way to manually force an invoice to PAID — the Arc transaction must be observed and verified first.