Skip to main content
An Invoice represents an invoice that a Business has collected for goods and services provided. Invoices are used to pass information about sales and accounts receivable into Layer.

​
Attributes

​
id
string
required
Unique identifier for the invoice.
​
type
string
required
Resource type. Value will be “Invoice”.
​
external_id
string
Unique ID of the invoice in your system for linking purposes.
​
business_id
string
required
ID of the Business that generated the invoice.
​
status
enum
required
Status of the invoice. Values can be: SENT, PARTIALLY_PAID, PAID, VOIDED, PARTIALLY_WRITTEN_OFF, WRITTEN_OFF, REFUNDED
​
sent_at
ISO8601 timestamp
required
When the invoice was sent by the business to the recipient.
​
due_at
ISO8601 timestamp
When the invoice is due.
​
paid_at
ISO8601 timestamp
When the invoice was paid.
​
voided_at
ISO8601 timestamp
When the invoice was voided. Voiding excludes the invoice from accounting.
​
invoice_number
string
Number for the invoice for display to end-users.
​
refund_allocations
array of RefundAllocation objects
List of Refund Allocations associated with this invoice.
​
customer
Customer object
required
Customer object associated with the invoice.
​
line_items
array of InvoiceLineItem objects
required
Line items making up the invoice.
​
subtotal
integer
required
Subtotal of all invoice line items in cents.
​
additional_discount
integer
Additional discount applied to the whole invoice in addition to individual line items.
​
total_discount
integer
Sum of all discount amounts across the invoice line items and any additional discounts in cents.
​
additional_sales_taxes
Array of SalesTax objects
​
total_tax
integer
Sum of all taxes across the invoice line items and any additional taxes in cents.
​
tips
integer
Tips included by the buyer, in cents.
​
tips_account
object
The Account Identifier for a tips account. If not specified, tips will be attributed to the Chart of Account’s default tips account, default a liability account. Alternate accounts can be specified in case tips should be tracked as revenue.
​
total
integer
required
Total amount of the invoice in cents.
​
outstanding_balance
integer
required
The remaining balance on the invoice after factoring in all previous invoice payments and write-offs.
​
memo
string
Memo for any text you would like to associate with the invoice (for example, to display to end users).
​
metadata
object
Arbitrary custom metadata in JSON format with a size limit of 1KB.
​
reference_number
string
Any (typically user-visible) identifier you would like to associate with the invoice. Can be used to filter when listing invoices.
​
transaction_tags
Array of Tags
​
payment_allocations
array of InvoicePaymentAllocation objects
Payments made by a customer are allocated toward one or many invoices. This list shows which payments have been been allocated towards this invoice. The most common case is that there is a 1:1 relationship between a payment and an invoice, in which case the allocation’s amount will match the payment’s amount.
​
write_offs
array of Invoice Write-Off objects
Write-offs applied to the invoice. See the Write-Off object for more information.
​
transaction_tags
Array of Tags
​
metadata
json object
Arbitrary metadata you can include with the invoice
​
imported_at
ISO8601 timestamp
required
Time when the invoice was first imported into Layer. Eligible sort key.
​
updated_at
ISO8601 timestamp
required
Time when the invoice was last updated in Layer. Eligible sort key.
{
  "data": {
    "type": "Invoice",
    "id": "c635d706-bf18-41a1-b4ea-83a4768b6e14",
    "business_id": "188eb399-f171-4849-861c-5c02d91f800b",
    "external_id": "1",
    "status": "PARTIALLY_PAID",
    "sent_at": "2024-06-04T18:11:57.184157Z",
    "due_at": "2024-06-05T18:11:57.184158Z",
    "paid_at": null,
    "voided_at": null,
    "invoice_number": "1",
    "memo": "Memo for the invoice",
    "customer": {
      "id": "a4c38874-8c01-4986-b8d0-4f159a52dd39",
      "external_id": "customer-1",
      "individual_name": null,
      "company_name": null,
      "email": null,
      "mobile_phone": null,
      "office_phone": null,
      "address_string": null,
      "notes": null,
      "status": "ACTIVE"
    },
    "line_items": [
      {
        "id": "733de30f-db72-4d52-98c5-fe070d4433f7",
        "external_id": "invoice-line-item-1",
        "invoice_id": "c635d706-bf18-41a1-b4ea-83a4768b6e14",
        "account_identifier": {
          "type": "AccountId",
          "id": "80b708b5-7b27-456c-9fb1-b8b918241908"
        },
        "description": "my test description",
        "product": "test line item",
        "unit_price": 50,
        "quantity": "2.00",
        "subtotal": 100,
        "discount_amount": 0,
        "sales_taxes_total": 0,
        "total_amount": 100,
        "refund_allocations": [],
        "transaction_tags": [
          {
            "id": "b2c3d4e5-f6a7-8901-bcde-f1234567890a",
            "key": "product-category",
            "value": "cleaning-supplies",
            "dimension_display_name": "Product Category",
            "value_display_name": "Cleaning Supplies",
            "dimension_id": "e3f4a5b6-c7d8-9012-cdef-123456789012",
            "definition_id": "f4a5b6c7-d8e9-0123-def1-234567890123",
            "created_at": "2024-02-27T02:16:40.389772Z",
            "updated_at": "2024-02-27T02:16:40.389772Z",
            "deleted_at": null,
            "archived_at": null
          }
        ]
      }
    ],
    "subtotal": 100,
    "additional_discount": 0,
    "additional_sales_taxes": [],
    "additional_sales_taxes_total": 0,
    "tips": 0,
    "tips_account": null,
    "total_amount": 100,
    "outstanding_balance": 10,
    "payment_allocations": [
      {
        "invoice_id": "c635d706-bf18-41a1-b4ea-83a4768b6e14",
        "payment_id": "590ed436-c2bd-4e39-8047-f913a852f99c",
        "amount": 90,
        "payment": {
          "id": "590ed436-c2bd-4e39-8047-f913a852f99c",
          "external_id": "payment-1",
          "at": "2024-01-01T00:00:00Z",
          "method": "CREDIT_CARD",
          "fee": 20,
          "additional_fees": [],
          "amount": 90,
          "processor": "STRIPE",
          "imported_at": "2024-06-04T18:11:57.339076Z",
          "allocations": [
            {
              "invoice_id": "c635d706-bf18-41a1-b4ea-83a4768b6e14",
              "payment_id": "590ed436-c2bd-4e39-8047-f913a852f99c",
              "amount": 90,
              "transaction_tags": []
            }
          ],
          "refund_allocations": [],
          "transaction_tags": []
        },
        "transaction_tags": [
          {
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "key": "department",
            "value": "sales",
            "dimension_display_name": "Department",
            "value_display_name": "Sales Team",
            "dimension_id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
            "definition_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
            "created_at": "2024-02-27T02:16:40.389772Z",
            "updated_at": "2024-02-27T02:16:40.389772Z",
            "deleted_at": null,
            "archived_at": null
          }
        ],
        "metadata": {}
      }
    ],
    "write_offs": [],
    "refund_allocations": []
    "imported_at": "2024-06-04T18:11:57.234148Z",
    "updated_at": null,
    "transaction_tags": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "key": "department",
        "value": "sales",
        "dimension_display_name": "Department",
        "value_display_name": "Sales Team",
        "dimension_id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
        "definition_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
        "created_at": "2024-02-27T02:16:40.389772Z",
        "updated_at": "2024-02-27T02:16:40.389772Z",
        "deleted_at": null,
        "archived_at": null
      }
    ],
    "metadata": {}
  }
}