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).
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
400Invalid body or Idempotency-Key or booksId

