Skip to main content
POST
/
v1
/
businesses
/
{businessId}
/
invoices
/
bulk
Bulk create invoices
curl --request POST \
  --url https://sandbox.layerfi.com/v1/businesses/{businessId}/invoices/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "external_id": "019234",
    "sent_at": "2023-11-07T05:31:56Z",
    "due_at": "2023-11-07T05:31:56Z",
    "voided_at": "2023-11-07T05:31:56Z",
    "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "customer_external_id": "<string>",
    "line_items": [
      {
        "account_identifier": {
          "type": "AccountId",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        },
        "prepayment_account_identifier": {
          "type": "Single_Chart_Account",
          "id": {
            "type": "AccountId",
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          },
          "name": "Current Assets",
          "account_number": "4000",
          "account_type": {
            "display_name": "Asset"
          },
          "account_subtype": {
            "display_name": "Current Assets"
          }
        },
        "external_id": "<string>",
        "description": "Line item description",
        "product": "Widgets",
        "unit_price": 123,
        "quantity": 123,
        "discount_amount": 123,
        "sales_taxes": [
          {
            "amount": 123,
            "tax_account": {
              "name": "CALIFORNIA_VAT",
              "type": "Tax_Name"
            }
          }
        ],
        "dedicated_refunds": [
          {
            "external_id": "31415926535",
            "account_identifier": {
              "type": "AccountId",
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            },
            "line_items": [
              {
                "amount": 123,
                "external_id": "<string>",
                "account_identifier": {
                  "type": "AccountId",
                  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
                },
                "prepayment_account_identifier": {
                  "type": "AccountId",
                  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
                },
                "tags": [
                  {
                    "key": "department",
                    "value": "sales",
                    "dimension_display_name": "Department",
                    "value_display_name": "Sales Department"
                  }
                ],
                "memo": "<string>",
                "metadata": {
                  "custom_field": "value",
                  "any valid json": "below 1kb",
                  "nested": {
                    "meaning of life": 42,
                    "array": []
                  }
                },
                "reference_number": "<string>"
              }
            ],
            "completed_at": "2023-11-07T05:31:56Z",
            "refund_processing_fee": 123,
            "processor": "<string>",
            "refunded_payment_fees": [
              {
                "account": {
                  "type": "AccountId",
                  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
                },
                "fee_amount": 123,
                "description": "<string>"
              }
            ],
            "tags": [
              {
                "key": "department",
                "value": "sales",
                "dimension_display_name": "Department",
                "value_display_name": "Sales Department"
              }
            ],
            "memo": "<string>",
            "metadata": {
              "custom_field": "value",
              "any valid json": "below 1kb",
              "nested": {
                "meaning of life": 42,
                "array": []
              }
            },
            "reference_number": "<string>",
            "payment_clearing_account_identifier": {
              "type": "AccountId",
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            }
          }
        ],
        "tags": [
          {
            "key": "department",
            "value": "sales",
            "dimension_display_name": "Department",
            "value_display_name": "Sales Department"
          }
        ],
        "time_entry_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      }
    ],
    "additional_sales_taxes": [
      {
        "amount": 123,
        "tax_account": {
          "name": "CALIFORNIA_VAT",
          "type": "Tax_Name"
        }
      }
    ],
    "additional_discount": 123,
    "tips": 123,
    "tips_account": {
      "type": "AccountId",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    },
    "payments": [
      {
        "external_id": "12345",
        "fee": 123,
        "amount": 123,
        "processor": "STRIPE",
        "payment_clearing_account_identifier": {
          "type": "AccountId",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        },
        "dedicated_refunds": [
          {
            "external_id": "31415926535",
            "account_identifier": {
              "type": "AccountId",
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            },
            "line_items": [
              {
                "amount": 123,
                "external_id": "<string>",
                "account_identifier": {
                  "type": "AccountId",
                  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
                },
                "prepayment_account_identifier": {
                  "type": "AccountId",
                  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
                },
                "tags": [
                  {
                    "key": "department",
                    "value": "sales",
                    "dimension_display_name": "Department",
                    "value_display_name": "Sales Department"
                  }
                ],
                "memo": "<string>",
                "metadata": {
                  "custom_field": "value",
                  "any valid json": "below 1kb",
                  "nested": {
                    "meaning of life": 42,
                    "array": []
                  }
                },
                "reference_number": "<string>"
              }
            ],
            "completed_at": "2023-11-07T05:31:56Z",
            "refund_processing_fee": 123,
            "processor": "<string>",
            "refunded_payment_fees": [
              {
                "account": {
                  "type": "AccountId",
                  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
                },
                "fee_amount": 123,
                "description": "<string>"
              }
            ],
            "tags": [
              {
                "key": "department",
                "value": "sales",
                "dimension_display_name": "Department",
                "value_display_name": "Sales Department"
              }
            ],
            "memo": "<string>",
            "metadata": {
              "custom_field": "value",
              "any valid json": "below 1kb",
              "nested": {
                "meaning of life": 42,
                "array": []
              }
            },
            "reference_number": "<string>",
            "payment_clearing_account_identifier": {
              "type": "AccountId",
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            }
          }
        ],
        "tags": [
          {
            "key": "department",
            "value": "sales",
            "dimension_display_name": "Department",
            "value_display_name": "Sales Department"
          }
        ],
        "memo": "<string>",
        "metadata": {
          "custom_field": "value",
          "any valid json": "below 1kb",
          "nested": {
            "meaning of life": 42,
            "array": []
          }
        },
        "reference_number": "<string>"
      }
    ],
    "dedicated_refunds": [
      {
        "external_id": "31415926535",
        "account_identifier": {
          "type": "AccountId",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        },
        "line_items": [
          {
            "amount": 123,
            "external_id": "<string>",
            "account_identifier": {
              "type": "AccountId",
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            },
            "prepayment_account_identifier": {
              "type": "AccountId",
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            },
            "tags": [
              {
                "key": "department",
                "value": "sales",
                "dimension_display_name": "Department",
                "value_display_name": "Sales Department"
              }
            ],
            "memo": "<string>",
            "metadata": {
              "custom_field": "value",
              "any valid json": "below 1kb",
              "nested": {
                "meaning of life": 42,
                "array": []
              }
            },
            "reference_number": "<string>"
          }
        ],
        "completed_at": "2023-11-07T05:31:56Z",
        "refund_processing_fee": 123,
        "processor": "<string>",
        "refunded_payment_fees": [
          {
            "account": {
              "type": "AccountId",
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            },
            "fee_amount": 123,
            "description": "<string>"
          }
        ],
        "tags": [
          {
            "key": "department",
            "value": "sales",
            "dimension_display_name": "Department",
            "value_display_name": "Sales Department"
          }
        ],
        "memo": "<string>",
        "metadata": {
          "custom_field": "value",
          "any valid json": "below 1kb",
          "nested": {
            "meaning of life": 42,
            "array": []
          }
        },
        "reference_number": "<string>",
        "payment_clearing_account_identifier": {
          "type": "AccountId",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      }
    ],
    "tags": [
      {
        "key": "department",
        "value": "sales",
        "dimension_display_name": "Department",
        "value_display_name": "Sales Department"
      }
    ],
    "memo": "<string>",
    "metadata": {
      "custom_field": "value",
      "any valid json": "below 1kb",
      "nested": {
        "meaning of life": 42,
        "array": []
      }
    },
    "reference_number": "<string>"
  }
]
'
{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "Invoice",
      "business_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "external_id": "1",
      "sent_at": "2023-11-07T05:31:56Z",
      "due_at": "2023-11-07T05:31:56Z",
      "paid_at": "2023-11-07T05:31:56Z",
      "voided_at": "2023-11-07T05:31:56Z",
      "line_items": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "external_id": "<string>",
          "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "account_identifier": {
            "type": "AccountId",
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          },
          "ledger_account": {
            "type": "Single_Chart_Account",
            "id": {
              "type": "AccountId",
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            },
            "name": "Current Assets",
            "account_number": "4000",
            "stable_name": {
              "type": "StableName",
              "stable_name": "CURRENT_ASSETS"
            },
            "account_type": {
              "display_name": "Asset"
            },
            "account_subtype": {
              "display_name": "Current Assets"
            }
          },
          "prepayment_account": {
            "type": "Single_Chart_Account",
            "id": {
              "type": "AccountId",
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            },
            "name": "Current Assets",
            "account_number": "4000",
            "stable_name": {
              "type": "StableName",
              "stable_name": "CURRENT_ASSETS"
            },
            "account_type": {
              "display_name": "Asset"
            },
            "account_subtype": {
              "display_name": "Current Assets"
            }
          },
          "description": "Widget sale",
          "product": "Widget",
          "unit_price": 123,
          "quantity": 123,
          "subtotal": 123,
          "discount_amount": 123,
          "sales_taxes_total": 123,
          "sales_taxes": [
            {
              "tax_account": {
                "name": "CALIFORNIA_VAT",
                "type": "Tax_Name"
              },
              "tax_ledger_account": {
                "id": "c4007474-f604-4d57-9690-b7f40f7a1cee",
                "name": "Sales tax: CALIFORNIA",
                "stable_name": "SALES_TAXES_PAYABLE:CALIFORNIA",
                "normality": "CREDIT",
                "account_type": {
                  "value": "LIABILITY",
                  "display_name": "Liabilities"
                },
                "account_subtype": {
                  "value": "SALES_TAXES_PAYABLE",
                  "display_name": "Sales Taxes Payable"
                }
              },
              "amount": 123
            }
          ],
          "total_amount": 123,
          "refund_allocations": [],
          "transaction_tags": [
            {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "key": "ExampleTagKey",
              "value": "ExampleTagValue",
              "dimension_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "definition_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "dimension_display_name": "<string>",
              "value_display_name": "<string>",
              "archived_at": "2023-11-07T05:31:56Z"
            }
          ]
        }
      ],
      "subtotal": 123,
      "additional_discount": 123,
      "additional_sales_taxes_total": 123,
      "additional_sales_taxes": [
        {
          "tax_account": {
            "name": "CALIFORNIA_VAT",
            "type": "Tax_Name"
          },
          "tax_ledger_account": {
            "id": "c4007474-f604-4d57-9690-b7f40f7a1cee",
            "name": "Sales tax: CALIFORNIA",
            "stable_name": "SALES_TAXES_PAYABLE:CALIFORNIA",
            "normality": "CREDIT",
            "account_type": {
              "value": "LIABILITY",
              "display_name": "Liabilities"
            },
            "account_subtype": {
              "value": "SALES_TAXES_PAYABLE",
              "display_name": "Sales Taxes Payable"
            }
          },
          "amount": 123
        }
      ],
      "tips": 123,
      "total_amount": 123,
      "outstanding_balance": 123,
      "memo": "<string>",
      "payment_allocations": [],
      "refund_allocations": [],
      "imported_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "transaction_tags": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "key": "ExampleTagKey",
          "value": "ExampleTagValue",
          "dimension_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "definition_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "dimension_display_name": "<string>",
          "value_display_name": "<string>",
          "archived_at": "2023-11-07T05:31:56Z"
        }
      ],
      "metadata": {
        "custom_field": "value",
        "any valid json": "below 1kb",
        "nested": {
          "meaning of life": 42,
          "array": []
        }
      },
      "reference_number": "<string>"
    }
  ]
}
This endpoint is deprecated. Use the Batch create invoices endpoint instead, which supports both all-or-nothing and partial success modes.

​
Rate Limiting

This endpoint has a custom rate limit policy. Rate Limit Details:
EnvironmentLimitRefill PeriodInitial Size
Sandbox20 requests1 second40 requests
Production20 requests1 second40 requests
Response Headers: All responses include the following rate limit headers:
  • X-RateLimit-Limit: the maximum number of requests that the client is permitted to make per the second
  • X-RateLimit-Remaining: the number of requests remaining in the current rate limit window
  • X-RateLimit-Reset: the UNIX timestamp at which the current rate limit window resets
For more details on rate limiting, see Rate Limiting.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Content-Type
string

Content-Type must be set to application/json.

Path Parameters

​
businessId
string
required

The UUID of the business to create invoices for.

Body

application/json
​
external_id
string

External ID for the invoice within your platform. Idempotency key.

Example:

"019234"

​
sent_at
string<date-time>

When the invoice was sent by the business to the recipient.

​
due_at
string<date-time>

When the invoice is due.

​
voided_at
string<date-time>

When the invoice was voided. Voiding excludes the invoice entirely from accounting.

​
customer_id
string<uuid>

ID of the customer to associate with the invoice. Either customer_id or customer_external_id must be provided.

​
customer_external_id
string

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
object[]

Line items making up the invoice.

​
additional_sales_taxes
object[]

List of additional sales tax obligations on the invoice outside individual line items.

​
additional_discount
integer

Additional discount applied to the whole invoice in addition to individual line items.

​
tips
integer

Tips included by the buyer, in cents.

​
tips_account
Account ID · object

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.

​
payments
object[] | null

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. When upserting an existing invoice: omitting this field (or passing null) preserves any existing dedicated payments; passing an empty array [] removes all dedicated payments. Non-dedicated payments (those independently recorded or included in a payout) are never removed by this field.

​
dedicated_refunds
object[]

Dedicated refunds to associate with this invoice.

​
tags
object[]
​
memo
string | null

Memo for any text you would like to associate with the invoice (for example, to display to end users).

​
metadata
object | null

Arbitrary custom metadata in JSON format with a size limit of 1KB.

Example:
{
  "custom_field": "value",
  "any valid json": "below 1kb",
  "nested": { "meaning of life": 42, "array": [] }
}
​
reference_number
string | null

Any (typically user-visible) identifier you would like to associate with the invoice. Can be used to filter when listing invoices.

Response

​
data
object[]
required