Skip to main content
The Retempo API is a REST API that lets you programmatically manage services, payment plans, checkout sessions, usage events, invoices, and on-chain USDC settlements. All resources are accessible under https://api.retempo.xyz/api/v1. Every request and response uses JSON, and your API key is sent with each call.

​
Base URL

https://api.retempo.xyz
All API endpoints are mounted under /api/v1. Construct the full URL for any request by appending the endpoint path: 
https://api.retempo.xyz/api/v1/<endpoint>

​
Request Format

All POST requests must include a Content-Type: application/json header and send a valid JSON object as the body. GET requests do not require a body. 
Content-Type: application/json
Example POST request: 
curl -X POST https://api.retempo.xyz/api/v1/services \
  -H "Content-Type: application/json" \
  -d '{ "name": "My Service" }'
Requests that omit Content-Type: application/json on write operations will receive a 400 Bad Request response with { "error": "Request body must be a JSON object." }.

​
Response Format

Every response body is JSON. Successful responses return the created or retrieved resource nested under a named key (for example, service, plan, or invoice). Error responses return a single error string describing what went wrong. Success shape: 
{
  "service": { "id": "clz1abc2def3ghi4", "name": "DataStream Pro" }
}
Error shape: 
{
  "error": "Service was not found."
}
HTTP status codes follow standard REST conventions: 200 for successful reads and idempotent returns, 201 for successful creates, 400 for validation errors, 404 for missing resources, 409 for conflicts, and 500 for unexpected server errors.

​
Endpoints Summary

MethodEndpointDescription
POST/api/v1/servicesCreate a new service
GET/api/v1/servicesList all services
GET/api/v1/services/:serviceIdGet a single service by ID
POST/api/v1/services/:serviceId/plansCreate a payment plan for a service
GET/api/v1/services/:serviceId/plansList all plans for a service
POST/api/v1/checkout-sessionsCreate a checkout session
GET/api/v1/checkout-sessions/:checkoutSessionIdGet a checkout session by ID
POST/api/v1/usage-eventsRecord a usage event
POST/api/v1/invoicesCreate an invoice
GET/api/v1/invoices/:invoiceIdGet a single invoice by ID
POST/api/v1/settlementsSubmit a USDC settlement
GET/api/v1/settlements/:settlementIdGet a settlement by ID

​
Health Check

Verify that the API is reachable at any time by calling the health endpoint. This endpoint requires no authentication and returns basic service information. 
curl https://api.retempo.xyz/health

{
  "ok": true,
  "service": "Retempo",
  "apiRoot": "/api/v1"
}
Use the health check endpoint in your deployment pipelines or monitoring dashboards to confirm API availability before sending live traffic.

​
Explore Key Sections

Create a Service

Register a new service and assign an owner. Services are the top-level resource that payment plans, checkout sessions, and settlements attach to.

Create a Plan

Define a payment plan for your service — fixed recurring, usage-based, or one-time — priced in USDC with a configurable billing interval.

Create a Checkout Session

Generate a checkout session that lets a payer subscribe to one of your plans with USDC.

Submit a Settlement

Submit an on-chain USDC settlement to record confirmed payment and close an invoice.