Batch create invoices
Create multiple invoices in a single request. Supports an optional allow_partial_success mode that commits each invoice independently, returning 207 Multi-Status when results are mixed.
Documentation Index
Fetch the complete documentation index at: https://docs.layerfi.com/llms.txt
Use this file to discover all available pages before exploring further.
Modes
This endpoint supports two modes of operation controlled by theallow_partial_success query parameter.
All-or-nothing (default)
Whenallow_partial_success is omitted or false, the request behaves as a single atomic operation. If any invoice fails validation or creation, the entire batch is rolled back and a 4xx error is returned. No invoices are persisted.
This is equivalent to the /bulk endpoint, but always returns the BatchCreateInvoicesResponse envelope (with an empty failed_invoices map on success).
Partial success
Whenallow_partial_success=true, each invoice is created in its own independent transaction. A failure on one invoice does not roll back invoices that have already succeeded.
successful_invoices— invoices that were committed.failed_invoices— a map from a failure key to a failure object with amessageand optional machine-readablecodefor invoices that did not persist.
207 Multi-Status is returned when at least one invoice fails and at least one succeeds. 200 OK is returned when all invoices succeed (even in partial-success mode).
Failure keys
Each entry infailed_invoices is keyed by a human-readable identifier derived in this order:
- The invoice’s
external_id - The invoice’s
reference_number unknown-N(zero-based counter) if neither is set
#1, #2, etc. (e.g. ref-2, ref-2#1).
Rate Limiting
This endpoint has a custom rate limit policy. Rate Limit Details:| Environment | Limit | Refill Period | Initial Size |
|---|---|---|---|
| Sandbox | 20 requests | 1 second | 40 requests |
| Production | 20 requests | 1 second | 40 requests |
- X-RateLimit-Limit: The rate limit bucket capacity
- X-RateLimit-Remaining: The number of tokens remaining in the bucket
- X-RateLimit-Reset: UTC timestamp (in seconds) when the bucket will be refilled
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Content-Type must be set to application/json.
Path Parameters
The UUID of the business to create invoices for.
Query Parameters
When true, invoices are committed individually so that a failure on one invoice does not roll back the others. Defaults to false (all-or-nothing).
Body
External ID for the invoice within your platform. Idempotency key.
"019234"
When the invoice was sent by the business to the recipient.
When the invoice is due.
When the invoice was voided. Voiding excludes the invoice entirely from accounting.
ID of the customer to associate with the invoice. Either customer_id or customer_external_id must be provided.
External ID of the customer to associate with the invoice. Either customer_id or customer_external_id must be provided. If the customer does not already exist, Layer will create it using this external ID.
Line items making up the invoice.
List of additional sales tax obligations on the invoice outside individual line items.
Additional discount applied to the whole invoice in addition to individual line items.
Tips included by the buyer, in cents.
The Account Identifier for a tips account. If not specified, Layer uses the chart's default tips account, which is typically a liability account. Specify a different account if tips should be tracked as revenue.
- Account ID
- Account Stable Name
Payments that have been made towards the balance of the invoice. Include these to create an immediately paid or partially paid invoice in the same API call.
Dedicated refunds to associate with this invoice.
Memo for any text you would like to associate with the invoice (for example, to display to end users).
Arbitrary custom metadata in JSON format with a size limit of 1KB.
{
"custom_field": "value",
"any valid json": "below 1kb",
"nested": { "meaning of life": 42, "array": [] }
}Any (typically user-visible) identifier you would like to associate with the invoice. Can be used to filter when listing invoices.
Response
All invoices were created successfully.
Response from the batch invoice creation endpoint, containing both successful and failed invoices.
Invoices that were successfully created.
Map of failed invoices keyed by an identifier derived from the invoice's external_id, reference_number, or unknown-N if neither is present. When two failed invoices share the same base key, subsequent entries are suffixed with #1, #2, etc.