> ## 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.
# Quickstart: Build Your First Retempo Integration End-to-End
> Create your first service, add a payment plan, open a checkout session, issue an invoice, and confirm a settlement with Retempo's API.
By the end of this guide you will have a fully wired Retempo integration: a live service with a monthly USDC payment plan, a checkout session ready to onboard a subscriber, an open invoice, and a settlement submitted to Arc for onchain confirmation. Every step maps to a single API call against `https://api.retempo.xyz`.
A service represents what you are selling. Send a `POST` request to `/api/v1/services` with a name, an optional description, and the owner's email address. Set `status` to `ACTIVE` so that subscribers can check out immediately.
```curl theme={null}
curl --request POST \
--url https://api.retempo.xyz/api/v1/services \
--header 'Content-Type: application/json' \
--data '{
"name": "Inference API",
"description": "High-throughput LLM inference endpoint with usage-based and fixed plans.",
"owner": {
"email": "you@example.com"
},
"status": "ACTIVE"
}'
```
Retempo returns the new service record, including its generated `id`. Copy the `id` — you will use it in the next step.
```json theme={null}
{
"service": {
"id": "svc_01j9kqzr2e4f5g6h7j8k9l0m",
"name": "Inference API",
"description": "High-throughput LLM inference endpoint with usage-based and fixed plans.",
"owner": {
"email": "you@example.com"
},
"status": "ACTIVE",
"createdAt": "2024-11-01T10:00:00.000Z",
"updatedAt": "2024-11-01T10:00:00.000Z"
}
}
```
A payment plan defines the price and billing cadence for your service. Post to `/api/v1/services/:serviceId/plans`, replacing `:serviceId` with the `id` you received above. This example creates a fixed \$49.00 USDC monthly plan.
```curl theme={null}
curl --request POST \
--url https://api.retempo.xyz/api/v1/services/svc_01j9kqzr2e4f5g6h7j8k9l0m/plans \
--header 'Content-Type: application/json' \
--data '{
"name": "Pro Monthly",
"pricingType": "FIXED_RECURRING",
"billingInterval": "MONTH",
"amount": "49.00",
"currency": "USDC"
}'
```
The response includes the plan's `id`. Copy both `serviceId` and `planId` — you will need them for the checkout session.
```json theme={null}
{
"plan": {
"id": "plan_02k1lrzs3f5g6h7j8k9l0m1n",
"serviceId": "svc_01j9kqzr2e4f5g6h7j8k9l0m",
"name": "Pro Monthly",
"pricingType": "FIXED_RECURRING",
"billingInterval": "MONTH",
"amount": "49.00",
"currency": "USDC",
"createdAt": "2024-11-01T10:01:00.000Z",
"updatedAt": "2024-11-01T10:01:00.000Z"
}
}
```
A checkout session gives your subscriber a way to complete payment and activate their subscription. Post to `/api/v1/checkout-sessions` with the `serviceId` and `paymentPlanId`. The session starts in `PENDING` status and includes an `id` you can use to build a checkout URL pointing to `https://retempo.xyz/checkout/:checkoutSessionId`.
```curl theme={null}
curl --request POST \
--url https://api.retempo.xyz/api/v1/checkout-sessions \
--header 'Content-Type: application/json' \
--data '{
"serviceId": "svc_01j9kqzr2e4f5g6h7j8k9l0m",
"paymentPlanId": "plan_02k1lrzs3f5g6h7j8k9l0m1n"
}'
```
When the subscriber completes the session, Retempo automatically creates a subscription and the session status moves from `PENDING` to `PAID`.
```json theme={null}
{
"checkoutSession": {
"id": "cs_03l2msat4g6h7j8k9l0m1n2o",
"serviceId": "svc_01j9kqzr2e4f5g6h7j8k9l0m",
"paymentPlanId": "plan_02k1lrzs3f5g6h7j8k9l0m1n",
"status": "PENDING",
"expiresAt": "2024-11-01T11:01:00.000Z",
"createdAt": "2024-11-01T10:02:00.000Z"
}
}
```
An invoice is the billing record for a subscription cycle. Post to `/api/v1/invoices` with the service, plan, and subscriber identifiers. Set `status` to `OPEN` to signal that the invoice is ready for settlement.
```curl theme={null}
curl --request POST \
--url https://api.retempo.xyz/api/v1/invoices \
--header 'Content-Type: application/json' \
--data '{
"serviceId": "svc_01j9kqzr2e4f5g6h7j8k9l0m",
"paymentPlanId": "plan_02k1lrzs3f5g6h7j8k9l0m1n",
"userId": "usr_subscriber_abc123",
"amount": "49.00",
"status": "OPEN"
}'
```
Copy the invoice `id` — you will reference it when you submit the settlement.
```json theme={null}
{
"invoice": {
"id": "inv_04m3ntbu5h7j8k9l0m1n2o3p",
"serviceId": "svc_01j9kqzr2e4f5g6h7j8k9l0m",
"paymentPlanId": "plan_02k1lrzs3f5g6h7j8k9l0m1n",
"userId": "usr_subscriber_abc123",
"amount": "49.00",
"currency": "USDC",
"status": "OPEN",
"createdAt": "2024-11-01T10:03:00.000Z",
"updatedAt": "2024-11-01T10:03:00.000Z"
}
}
```
A settlement submits the payment proof to Arc for onchain confirmation. Post to `/api/v1/settlements` with the invoice ID, a 32-byte hex reference hash, and the payer and merchant wallet addresses. Retempo submits the transaction to Arc and monitors for confirmation.
```curl theme={null}
curl --request POST \
--url https://api.retempo.xyz/api/v1/settlements \
--header 'Content-Type: application/json' \
--data '{
"invoiceId": "inv_04m3ntbu5h7j8k9l0m1n2o3p",
"referenceHash": "0xabc123def456abc123def456abc123def456abc123def456abc123def456abcd",
"payerAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
"merchantAddress": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B"
}'
```
Retempo creates the settlement record in `PENDING` status and submits the transaction to Arc. Once the chain confirms the transaction and records the settlement event, the status moves to `CONFIRMED` and the linked invoice is marked `PAID`.
```json theme={null}
{
"settlement": {
"id": "stl_05n4oucv6j8k9l0m1n2o3p4q",
"invoiceId": "inv_04m3ntbu5h7j8k9l0m1n2o3p",
"referenceHash": "0xabc123def456abc123def456abc123def456abc123def456abc123def456abcd",
"payerAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
"merchantAddress": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
"amount": "49.00",
"currency": "USDC",
"status": "PENDING",
"transactionHash": null,
"createdAt": "2024-11-01T10:04:00.000Z",
"updatedAt": "2024-11-01T10:04:00.000Z"
}
}
```
Settlements are only marked `CONFIRMED` after a real Arc transaction receipt is observed. Until then, the settlement remains in `PENDING` or `SUBMITTED` status and the invoice stays `OPEN`.