Core Concepts: Services, Plans, Invoices, and Settlements

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.

​

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: A service must be in 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: Billing intervals set the frequency: All amounts are denominated in USDC.

​

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: When a checkout session reaches 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.

​

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: An invoice is never marked 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: Every confirmed settlement stores:

• 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.