Skip to main content
Invoices are the billing record in Retempo. Each invoice captures the amount a subscriber owes for a given billing period, links that amount to a specific service and payment plan, and tracks the settlement that eventually closes it out. When a settlement is confirmed onchain, Retempo automatically flips the invoice to PAID — you never need to mark it manually.
Invoices cannot be created with a status of PAID. An invoice is marked PAID only after a real settlement is confirmed onchain via Arc. Attempting to create an invoice with status: "PAID" will return an error.

​
Creating an invoice

To create an invoice, send a POST request to /api/v1/invoices. You must supply a serviceId, paymentPlanId, userId (the subscriber being billed), and an amount. The currency defaults to USDC if omitted, and status defaults to DRAFT. Use dueAt to set a payment deadline and subscriptionId to attach the invoice to an active subscription cycle. 
curl --request POST \
  --url https://api.retempo.xyz/api/v1/invoices \
  --header 'Content-Type: application/json' \
  --data '{
    "serviceId": "svc_01hx9kz3v8mq2t4yw6npd7e",
    "paymentPlanId": "plan_01hx9m1bp4nq3s8zt7vce6r",
    "userId": "usr_01hx9n2fp8qt6s3bz4wmd5k",
    "amount": "49.000000",
    "currency": "USDC",
    "status": "OPEN",
    "dueAt": "2025-02-14T00:00:00.000Z",
    "subscriptionId": "sub_01hx9q4hr8su9v5da6yof7w"
  }'
A successful response returns the full invoice object along with embedded relations for the service, payment plan, user, settlements, subscription, and usage events: 
{
  "invoice": {
    "id": "inv_01hx9r5js9tv0w6eb7zpg8x",
    "serviceId": "svc_01hx9kz3v8mq2t4yw6npd7e",
    "paymentPlanId": "plan_01hx9m1bp4nq3s8zt7vce6r",
    "userId": "usr_01hx9n2fp8qt6s3bz4wmd5k",
    "status": "OPEN",
    "amount": "49.000000",
    "currency": "USDC",
    "dueAt": "2025-02-14T00:00:00.000Z",
    "createdAt": "2025-01-14T12:00:00.000Z",
    "service": {
      "id": "svc_01hx9kz3v8mq2t4yw6npd7e",
      "name": "DataStream Pro"
    },
    "paymentPlan": {
      "id": "plan_01hx9m1bp4nq3s8zt7vce6r",
      "name": "Pro Monthly",
      "pricingType": "FIXED_RECURRING",
      "billingInterval": "MONTH",
      "amount": "49.000000",
      "currency": "USDC"
    },
    "user": {
      "id": "usr_01hx9n2fp8qt6s3bz4wmd5k",
      "email": "agent@example.io"
    },
    "subscription": {
      "id": "sub_01hx9q4hr8su9v5da6yof7w",
      "status": "ACTIVE"
    },
    "settlements": [],
    "usageEvents": []
  }
}

​
Invoice statuses

An invoice moves through the following statuses during its lifetime:
StatusMeaning
DRAFTThe invoice has been created but not yet sent to the subscriber. Use DRAFT while you’re still assembling usage events or finalizing the amount. This is the default if you omit status.
OPENThe invoice is active and payment is due. Retempo will accept settlements against an OPEN invoice.
PAIDA settlement tied to this invoice has been confirmed on Arc. Retempo sets this status automatically — you cannot set it via the API.
VOIDThe invoice has been cancelled. No settlement can be applied to a voided invoice.
EXPIREDThe invoice passed its dueAt timestamp without being paid. Expired invoices are closed and no longer accept settlements.

​
Fetching invoice status

To check the current status of an invoice and see any settlements that have been applied, send a GET request with the invoice ID: 
curl --request GET \
  --url https://api.retempo.xyz/api/v1/invoices/inv_01hx9r5js9tv0w6eb7zpg8x \
  --header 'Content-Type: application/json'
Pay attention to the settlements array in the response — each entry represents an onchain settlement attempt against this invoice. Once a settlement reaches CONFIRMED, the invoice status will be PAID. 
{
  "invoice": {
    "id": "inv_01hx9r5js9tv0w6eb7zpg8x",
    "serviceId": "svc_01hx9kz3v8mq2t4yw6npd7e",
    "paymentPlanId": "plan_01hx9m1bp4nq3s8zt7vce6r",
    "userId": "usr_01hx9n2fp8qt6s3bz4wmd5k",
    "status": "PAID",
    "amount": "49.000000",
    "currency": "USDC",
    "dueAt": "2025-02-14T00:00:00.000Z",
    "paidAt": "2025-01-14T13:05:00.000Z",
    "createdAt": "2025-01-14T12:00:00.000Z",
    "service": {
      "id": "svc_01hx9kz3v8mq2t4yw6npd7e",
      "name": "DataStream Pro"
    },
    "paymentPlan": {
      "id": "plan_01hx9m1bp4nq3s8zt7vce6r",
      "name": "Pro Monthly",
      "pricingType": "FIXED_RECURRING",
      "billingInterval": "MONTH",
      "amount": "49.000000",
      "currency": "USDC"
    },
    "user": {
      "id": "usr_01hx9n2fp8qt6s3bz4wmd5k",
      "email": "agent@example.io"
    },
    "subscription": {
      "id": "sub_01hx9q4hr8su9v5da6yof7w",
      "status": "ACTIVE"
    },
    "settlements": [
      {
        "id": "stl_01hx9s6kt0uw1x7fc8aqh9y",
        "status": "CONFIRMED",
        "amount": "49.000000",
        "currency": "USDC",
        "referenceHash": "0xabc123def456abc123def456abc123def456abc123def456abc123def456abcd",
        "recordedAt": "2025-01-14T13:05:00.000Z"
      }
    ],
    "usageEvents": []
  }
}