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

# Issue and Track Invoices in Retempo

> Create invoices in Retempo to bill subscribers. Invoices track amount due and are automatically marked paid when a settlement is confirmed on Arc.

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.

<Warning>
  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.
</Warning>

## 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 theme={null}
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:

```json theme={null}
{
  "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 theme={null}
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`.

```json theme={null}
{
  "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": []
  }
}
```