Invoices

Returns a paginated list of invoices, optionally filtered by date range or order ID.

Response shape: { meta: { count, totalPages, page, limit, sortBy }, data: [...] }. Defaults: page=1, limit=10.

status values: draft, sent, overdue, paid-in-full, partially-paid, cancelled.

Money fields (amount, cost, tax, paidAmount, paidSurcharge, item prices) are in dollars.

Create a new invoice with line items, billing address. Accepts both standard and flexible item formats. Creating does not send any email/SMS; use the send-by-email / send-by-sms endpoints.

terms values: upon_receipt, 30, 60, 90 (days).

items: Array of { id, qty, taxes[] } — required. taxes is a list of tax ids (send [] when none).

amount / tax: computed by the server from the items; any value sent is ignored.

Monetary values in responses are in dollars (converted from cents).

billingAddress and showBilling control whether addresses are shown/required on the payment page.

customValues: Extra properties passed to the payment form. Keys must be pre-configured in the merchant setup; fields the merchant marked as required are mandatory, and select fields accept only the configured options.

applyDiscount: If applicable, applies a configured credit card discount.

customerId links the invoice to a customer vault.

overrideDefaultPaymentMethod: Override the default payment method from the customer vault.

Soft-deletes an invoice: sets deletedAt and cancels its payment request. Partially-paid invoices cannot be deleted. Returns the raw invoice as it was before deletion; money fields are integer cents (not converted).

Update an existing invoice. Cancelled invoices cannot be updated.

Every update regenerates paymentRequestId / paymentRequestUrl — previously shared links stop working.

items: { id, qty, taxes[] } entries; replaces all lines and recomputes totals when amount is omitted.

amount: when sent on update it is stored verbatim, as an integer amount in cents (1000 = $10.00), with no recomputation.

dueDate: must be after the invoice creation date.

billingAddress / shippingAddress: empty objects ({}) do not clear stored addresses.

status values: draft, overdue, sent, paid-in-full, partially-paid, cancelled (default: draft).

To cancel an invoice: Send { "status": "cancelled" }.

terms values (enforced on update): upon_receipt, 30, 60, 90.

applyDiscount: Apply/remove the configured credit card discount.

customValues: Update custom field values (keys must be pre-configured in merchant setup).

Send an invoice to a customer via email. email is required — nothing is sent without it.

Side effect: the invoice status becomes sent. Cancelled invoices cannot be sent.

An invoiceId field in the body is ignored; the path parameter wins.

Optional timezone query parameter (IANA name, default America/New_York) used when rendering dates.

Generate a PDF file for the given invoice. Returns a JSON object with fileName and fileUrl (the URL to download the PDF).

Retrieve a single invoice by ID.

Send a payment link for this invoice via SMS. Provide phoneNumber in the request body.

Phone format: ^[+]?[(]?[0-9]{3}[)]?[ ]?[0-9]{3}[-]?[0-9]{4}$ — e.g. (555) 555-5555 or 5555555555; 555-555-5555 and 786 322 0000 are rejected.

Side effect: the invoice status becomes sent. Cancelled invoices cannot be sent.

An invoiceId field in the body is ignored; the path parameter wins.