Skip to navigation
API ReferenceInvoices

Create an Invoice

Creates a draft Invoice in the key’s mode. It has no number and no working url until you send it. The total, with tax, must be under FJD 5,000.00 (at most 499999 cents), in Test mode and Live mode alike. The Idempotency-Key header is required: a retry with the same key returns the original draft instead of making a second.

Authentication

AuthorizationBearer

Your secret key: sk_test_… in Test mode, sk_live_… in Live mode.

Headers

idempotency-keystringRequired>=1 character

Client-generated key; a repeated key returns the original result instead of repeating the change.

Request

This endpoint expects an object.
customerNamestringRequired
Who you are billing, up to 100 characters.
dueDatestringRequired

YYYY-MM-DD, Pacific/Fiji.

itemslist of objectsRequired
1 to 50 line items, entered excluding tax.
customerEmailstringOptional
Optional until you email the Invoice from the dashboard.
taxLabelstringOptional

Label for the one optional tax line, such as VAT. Needs taxPercent.

taxPercentdoubleOptional
Tax as a percentage of the subtotal, up to 100 with 2 decimal places.
vatNumberstringOptional
Your VAT number, if you are registered.

Response

Draft created, or replayed from the Idempotency-Key.

idinteger
Invoice identifier.
numberstring or null

The Invoice number, such as INV-0007. Assigned when the Invoice is sent, so a draft has none; numbers are never reused.

statusenum

draft until sent and editable only from the dashboard. sent: the Customer can pay it. paid: paid in full. void: you voided it; it can no longer be paid.

Allowed values:
overdueboolean

A sent, unpaid Invoice past its due date (Pacific/Fiji). Derived, not a status; the Customer can still pay.

modeenum

test for an Invoice made with an sk_test_ key, live for an sk_live_ key.

Allowed values:
customerNamestring
Who you billed.
customerEmailstring or null
The Customer's email, if you gave one.
itemslist of objects
The line items, excluding tax.
taxLabelstring or null

Label of the tax line; null if none.

taxPercentdouble
0 when there is no tax line.
vatNumberstring or null
Your VAT number, if you gave one.
dueDatestring

YYYY-MM-DD, Pacific/Fiji.

subtotalinteger

Sum of the line items, in FJD cents (minor units).

taxinteger

The tax line, in FJD cents (minor units).

totalinteger

Amount due; under FJD 5,000.00, in FJD cents (minor units).

urlstring
The hosted page the Customer opens and pays on. Works once the Invoice is sent.
pdfUrlstring or null

Where to GET the PDF, with your secret key. Null on a draft.

createdAtinteger
Unix ms timestamp the draft was created.
sentAtinteger or null

Unix ms timestamp it was sent; null on a draft.

paidAtinteger or null

Unix ms timestamp it was paid; null until then.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error