Create an invoice (accounts receivable)

Creates a single invoice, i.e. an accounts receivable record of money a customer owes the organization, which books the matching journal entries. It takes the same input as the Books create-invoice form in Mercury. referenceNumber is the invoice number (the form's Invoice number field, for example INV-1042): required, 1 to 299 characters. customer is the customer to bill: a Mercury Invoicing customer ID from the Mercury Invoicing customers API (/ar/customers). effectiveDate is the invoice date and dueDate the due date (both YYYY-MM-DD). lines are the line items, at least one, each with a description, a ledgerId (the ledger account, such as a revenue ledger, from getBooksLedgers), and an amount in dollars; an amount may be negative (for example a discount), zero-amount lines are ignored, at least one line must be non-zero, and the line items must total more than zero. notes is an optional note. The invoice is created open; drafts, attachments, and service periods are not supported. When the organization uses the Mercury Invoicing integration, the invoice is also created in Mercury Invoicing, without emailing the customer, and its invoice number must be unique among all of the organization's Mercury invoices, of any status (a duplicate is rejected with HTTP 400). Without the integration the invoice is stored only in Books, which rejects a second invoice with the same invoice number for the same customer. The response is usually the created invoice (HTTP 200): its id, referenceNumber, customer (id and name), effectiveDate, dueDate, status, displayStatus, grossAmount, amountRemaining, lines, notes (omitted when none), and paymentApplications. If the invoice was created in Mercury Invoicing but has not synced to Books yet, the response is HTTP 202 with syncStatus pending, a message, and no id: the invoice exists, so do not create it again; once it has synced, find it in the invoice list by its invoice number (referenceNumber). To make retries safe, send an Idempotency-Key header: a replay with the same key and body returns the original status and body rather than creating a duplicate (a reused key with a different body is rejected with 422). If a request fails with a server error (HTTP 5xx), the invoice may already exist, so check for it rather than retrying with a new key. Request errors are returned as an HTTP error status and create nothing: a missing or invalid field, or a deleted customer (400); a token without the scope to create accrual sources, a customer that is not in the Books instance's organization (including one that does not exist), or a line ledger outside the Books instance or read-only (403); or, with the integration, an organization without a checking account to receive the invoice's payments (409).

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
uuid

The Books instance to act on. Must be the token organization's own instance, which it defaults to.

Body Params

A request to create a single invoice (accounts receivable).

uuid
required

The customer to bill (the Customer field of the form): a Mercury Invoicing customer ID of this organization, from the Mercury Invoicing customers API (/ar/customers).

date
required

The due date (the Due date field of the form), YYYY-MM-DD.

date
required

The invoice date (the Invoice date field of the form), YYYY-MM-DD. Books records the invoice on the earlier of this and dueDate.

lines
array of objects
required
length ≥ 1

The line items (the Line items table of the form). At least one is required.

lines*

A line item of the invoice to create.

double
required

The line item's amount, in dollars (the Amount column of the form). May be negative (e.g. a discount line). Zero-amount lines are ignored; at least one line must be non-zero, and the combined total of all lines must be greater than zero.

string
required
length between 1 and 1024

The line item's description (the Description column of the form). Required and non-empty; leading and trailing whitespace is stripped.

string
required

The ledger account to book this line against, such as a revenue ledger (the Ledger account column of the form). Use an ID from getBooksLedgers; it must be in this Books instance and not a Mercury bank-feed ledger.

string | null

An optional note (the Note field of the form).

string
required
length between 1 and 299

The invoice number, as in the Invoice number field of the form (for example INV-1042): the number the business gives the invoice and its customer sees. Required, 1 to 299 characters; leading and trailing whitespace is stripped. With the Mercury Invoicing integration it becomes the Mercury Invoicing invoice number and must be unique among all of the organization's Mercury invoices, of any status. Without it, it is stored only in Books, which rejects a second invoice with the same invoice number for the same customer.

Headers
string
Responses

400

Invalid body or Idempotency-Key or booksId

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