Issue and Track Invoices in Retempo

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:

Status	Meaning
`DRAFT`	The 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`.
`OPEN`	The invoice is active and payment is due. Retempo will accept settlements against an `OPEN` invoice.
`PAID`	A settlement tied to this invoice has been confirmed on Arc. Retempo sets this status automatically — you cannot set it via the API.
`VOID`	The invoice has been cancelled. No settlement can be applied to a voided invoice.
`EXPIRED`	The 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": []
  }
}

Get Started

Core Workflows

Usage Billing

Onchain Settlement

Reference

Issue and Track Invoices in Retempo

Creating an invoice

Invoice statuses

Fetching invoice status

​Creating an invoice

​Invoice statuses

​Fetching invoice status

Creating an invoice

Invoice statuses

Fetching invoice status