Invoices
POST /Payment/initiateInvoice creates an invoice and sends it to the customer's phone number. It returns the details your integration needs to continue the payment flow.
This endpoint requires a Bearer API token. Xara creates the invoice for the business connected to the authenticated account.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
customerPhoneNumber | string | Yes | The paying customer's phone number. |
items | array | Yes | One or more { product_id, quantity } entries. Each product must belong to the authenticated business. |
customerName | string | No | Customer name. Derived from the phone number when omitted. |
note | string | No | Free-text note stored on the invoice. |
includeVat | boolean | No | Uses the business VAT setting by default. Set it to false when the total must match an external checkout total. |
discountType | string | No | amount or percentage. |
discountValue | number | Conditional | Required when discountType is set. |
partialPaymentType | string | No | amount or percentage for the minimum upfront payment. |
partialPaymentValue | number | Conditional | Required when partialPaymentType is set. |
deliveryEta | string | No | Expected delivery date or time. |
delivery_address | object | No | Delivery details in the form { address, city?, state?, label? }. |
Each entry inside items contains the catalog item's product_id and its quantity. Xara calculates pricing from the business catalog.
Send items as a normal JSON array. Xara takes each item's price, name, and ticket or subscription details from the catalog.
Handle the response
The success response contains invoice information in data, including its reference, status, totals, items, and any stock warnings. Keep the returned invoice reference with your own order or checkout ID. The same reference appears in payment webhooks, so use it to match the payment to your order.
Do not mark an order as paid only because invoice creation succeeded. Wait for an invoice.paid webhook, verify its signature, and make sure you do not process the same delivery twice.