POST /api/v1/invoices — Create a Retempo Invoice

Creating an invoice generates a billing record that ties a subscriber to a specific amount owed under a payment plan. You control the initial status — use DRAFT for invoices you are not yet ready to collect on, or OPEN to immediately signal that payment is due. Retempo marks an invoice as PAID only after a confirmed settlement is recorded against it.

POST https://api.retempo.xyz/api/v1/invoices

Request Body

string

required

The ID of the service this invoice belongs to.

string

required

The ID of the payment plan associated with this invoice. The plan must belong to the specified service.

string

required

The ID of the existing Retempo user being billed.

string | number

required

The amount to bill, as a decimal string (e.g. "49.000000") or number. Must be a non-negative value.

string

default:"USDC"

The currency for the invoice. Defaults to USDC if omitted.

string

default:"DRAFT"

The initial status of the invoice. Accepted values: DRAFT, OPEN, VOID, EXPIRED. Defaults to DRAFT. You cannot set this to PAID on creation — doing so returns a 400 error.

string

An ISO 8601 datetime string specifying when payment is due. If omitted, no due date is set.

string

The ID of a subscription to associate with this invoice. Optional — use when the invoice is tied to an ongoing subscription. The subscription must belong to the same service and user.

Response

A successful request returns HTTP 201 Created with the new invoice object and all related records.

object

The newly created invoice with all related records included.

Show invoice fields

string

Unique identifier for the invoice.

string

ID of the associated service.

string

ID of the associated payment plan.

string

ID of the billed user.

string | null

ID of the linked subscription, or null.

string

Current invoice status: DRAFT, OPEN, VOID, or EXPIRED.

string

Billed amount as a decimal string with six decimal places.

string

Currency of the invoice.

string | null

Due date, or null if not set.

string | null

Always null on creation. Populated only after a settlement is confirmed.

string

ISO 8601 datetime the invoice was created.

object

Nested service object.

object

Nested payment plan object.

object

Nested user object.

object | null

Nested subscription object if subscriptionId was provided, otherwise null.

array

List of settlements recorded against this invoice. Empty on creation.

array

List of usage events linked to this invoice. Empty on creation.

201 — Invoice created

{
  "invoice": {
    "id": "clz1invoice999",
    "serviceId": "clz1abc2def3ghi4",
    "paymentPlanId": "clz1plan567",
    "userId": "clz1user111",
    "subscriptionId": null,
    "status": "OPEN",
    "amount": "49.000000",
    "currency": "USDC",
    "dueAt": "2025-07-01T00:00:00.000Z",
    "paidAt": null,
    "createdAt": "2025-06-01T10:15:00.000Z",
    "service": {
      "id": "clz1abc2def3ghi4",
      "name": "DataStream Pro",
      "status": "ACTIVE"
    },
    "paymentPlan": {
      "id": "clz1plan567",
      "name": "Pro Monthly",
      "amount": "49.000000",
      "currency": "USDC"
    },
    "user": {
      "id": "clz1user111",
      "email": "subscriber@example.com"
    },
    "subscription": null,
    "settlements": [],
    "usageEvents": []
  }
}

Example Request

curl -X POST https://api.retempo.xyz/api/v1/invoices \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "clz1abc2def3ghi4",
    "paymentPlanId": "clz1plan567",
    "userId": "clz1user111",
    "amount": "49.000000",
    "status": "OPEN",
    "dueAt": "2025-07-01T00:00:00.000Z"
  }'

Error Codes

Status	Message	Condition
`400 Bad Request`	`serviceId is required.`	`serviceId` was omitted.
`400 Bad Request`	`paymentPlanId is required.`	`paymentPlanId` was omitted.
`400 Bad Request`	`userId is required.`	`userId` was omitted.
`400 Bad Request`	`amount is required.`	`amount` was omitted.
`400 Bad Request`	`Invoices cannot be created as PAID without a real payment event.`	`status` was set to `PAID`.
`400 Bad Request`	`status must be one of: DRAFT, OPEN, PAID, VOID, EXPIRED.`	An unrecognized status value was provided.
`404 Not Found`	`Payment plan was not found for the service.`	The plan does not exist or does not belong to the specified service.
`404 Not Found`	`Referenced database record was not found.`	The `userId` was not found.
`404 Not Found`	`Subscription was not found for the service and user.`	The `subscriptionId` does not belong to the specified service and user.

You cannot create an invoice with status: "PAID". An invoice is only marked PAID automatically after a confirmed settlement is recorded against it.

Overview

Services

Payment Plans

Checkout & Invoicing

Settlements

POST /api/v1/invoices — Create a Retempo Invoice

Request Body

Response

201 — Invoice created

Example Request

Error Codes

​Request Body

​Response

​201 — Invoice created

​Example Request

​Error Codes

Request Body

Response

201 — Invoice created

Example Request

Error Codes