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

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

​
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.
Example POST request:
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:
Error shape:
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

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