Skip to main content
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

​
serviceId
string
required
The ID of the service this invoice belongs to.
​
paymentPlanId
string
required
The ID of the payment plan associated with this invoice. The plan must belong to the specified service.
​
userId
string
required
The ID of the existing Retempo user being billed.
​
amount
string | number
required
The amount to bill, as a decimal string (e.g. "49.000000") or number. Must be a non-negative value.
​
currency
string
default:"USDC"
The currency for the invoice. Defaults to USDC if omitted.
​
status
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.
​
dueAt
string
An ISO 8601 datetime string specifying when payment is due. If omitted, no due date is set.
​
subscriptionId
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.
​
invoice
object
The newly created invoice with all related records included.

​
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

StatusMessageCondition
400 Bad RequestserviceId is required.serviceId was omitted.
400 Bad RequestpaymentPlanId is required.paymentPlanId was omitted.
400 Bad RequestuserId is required.userId was omitted.
400 Bad Requestamount is required.amount was omitted.
400 Bad RequestInvoices cannot be created as PAID without a real payment event.status was set to PAID.
400 Bad Requeststatus must be one of: DRAFT, OPEN, PAID, VOID, EXPIRED.An unrecognized status value was provided.
404 Not FoundPayment plan was not found for the service.The plan does not exist or does not belong to the specified service.
404 Not FoundReferenced database record was not found.The userId was not found.
404 Not FoundSubscription 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.