Create Bill

Creates a bill of type sale, refund, void, layaway or foc (free-of-charge). Requires the p/c-bill permission on the bill location (voids at non-restaurant locations require p/d-bill). Pass is_cloud_settle: true to book the bill against the location's cloud register — the invoice number is then assigned server-side when number is omitted. Without is_cloud_settle a valid open register_session.id is required. The client is the source of truth for amounts: line and bill totals are stored as sent. A bill with no payments stays outstanding (payment_status: payment-pending) and can be settled later via the Payments endpoints. For refunds set parent_id to the original bill and send negative quantities/totals; the refund total must be negative. Note: the settled_at key must be present in the payload (JSON null is fine for an unsettled bill) — omitting the key entirely fails.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
required

Client-generated bill id (idempotency key). Re-posting the same id with the same total returns the already-saved bill.

string
enum
required
Allowed:
string | null

Bill subtype key (must exist in company bill-subtype types).

boolean

Book against the location cloud register instead of a client register session.

location
object
required

{"id":

register_session
object

{"id":

customer
object

{"id":

employee
object

{"id":

integer

Original bill id — required when type is refund.

string

Invoice number; when omitted the server assigns the next number for the register.

integer
number
required
number
required
number
required

Must be positive for sale, negative for refund.

number
number
integer | null
taxes
array

Bill-level taxes: [{id, on_amount, amount, rate}].

taxes
fees
array

Bill-level fees: [{id, amount, on_amount}] (id, amount, on_amount required per fee).

fees
bill_lines
array

Line items. Each requires variant.id, quantity, sales_price, total_sales_price, total_tax, total, sort_order; optional unit, unit_scale, unit_quantity, discount_amount, discount_percent, fixed_discount_id, note, taxes, serials, batches, modifiers, kit_items.

bill_lines
void_lines
array

Voided line records (restaurant): each requires variant.id, quantity, unit, unit_scale, unit_quantity, client_voided_at.

void_lines
payments
array

Payments to record on save: [{method, amount, extra}]. Zero-amount entries are ignored.

payments
string

Single-payment shorthand: method (cash, card, bank-transfer, credit, gift-card, loyalty, or a custom company payment type).

number

Amount for payment_method shorthand.

payment_extra
object | null
number

Cash tendered (with cash payment_method).

string
number
string
enum

Set at creation to make the bill a delivery bill (enables the delivery-status/driver endpoints).

Allowed:
table
object

Restaurant table: {"id":

, "cover": }.

address
object

Customer address: {"id":

}.

currency
object

Alternate bill currency: {"code", "rate"}.

integer | null
string
length ≤ 2048
string
length ≤ 250
tags
array
tags
string | null
string | null
integer
required

Unix timestamp — required.

integer | null

User id who rang the bill (attribution only; unresolvable ids degrade to null).

integer | null
required

Unix timestamp when settled. Key must be present; send null for an unsettled (outstanding) bill.

Headers
string
required

The merchant install this request acts on (install.store_id from the app.installed webhook).

Response

Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json