> ## 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.

# Invoice object

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

<ParamField body="id" type="string" required="true">
  Unique identifier for the invoice.
</ParamField>

<ParamField body="type" type="string" required="true">
  Resource type. Value will be "Invoice".
</ParamField>

<ParamField body="external_id" type="string">
  Unique ID of the invoice in your system for linking purposes.
</ParamField>

<ParamField body="business_id" type="string" required="true">
  ID of the Business that generated the invoice.
</ParamField>

<ParamField body="status" type="enum" required="true">
  Status of the invoice. Values can be: `SENT`, `PARTIALLY_PAID`,
  `PAID`, `VOIDED`, `PARTIALLY_WRITTEN_OFF`, `WRITTEN_OFF`, `REFUNDED`
</ParamField>

<ParamField body="sent_at" type="ISO8601 timestamp" required="true">
  When the invoice was sent by the business to the recipient.
</ParamField>

<ParamField body="due_at" type="ISO8601 timestamp">
  When the invoice is due.
</ParamField>

<ParamField body="paid_at" type="ISO8601 timestamp">
  When the invoice was paid.
</ParamField>

<ParamField body="voided_at" type="ISO8601 timestamp">
  When the invoice was voided. Voiding excludes the invoice from accounting.
</ParamField>

<ParamField body="invoice_number" type="string">
  Number for the invoice for display to end-users.
</ParamField>

<ParamField body="refund_allocations" type="array of RefundAllocation objects">
  List of [Refund Allocations](/api-reference/refunds/refund#refund-allocation-object) associated with this invoice.
</ParamField>

<ParamField body="customer" type="Customer object" required="true">
  [Customer](/api-reference/customer/customer) object associated with the invoice.
</ParamField>

<ParamField body="line_items" type="array of InvoiceLineItem objects" required="true">
  Line items making up the invoice.

  <Expandable title="InvoiceLineItem properties">
    <ResponseField name="id" type="string" required="true">
      ID of the invoice line item.
    </ResponseField>

    <ResponseField name="external_id" type="string">
      The external ID of the invoice line item in your system.
    </ResponseField>

    <ResponseField name="invoice_id" type="string" required="true">
      ID of the parent invoice
    </ResponseField>

    <ResponseField name="description" type="string">
      Description of the specific line item.
    </ResponseField>

    <ResponseField name="product" type="string">
      Reference to the product being sold.
    </ResponseField>

    <ResponseField name="quantity" type="float" required="true">
      Number of units sold.
    </ResponseField>

    <ResponseField name="unit_price" type="integer" required="true">
      The amount in cents of each unit.
    </ResponseField>

    <ResponseField name="discount_amount" type="integer">
      Total discount given to this line item, in cents.
    </ResponseField>

    <ParamField body="refund_allocations" type="array of RefundAllocation objects">
      List of [Refund Allocations](/api-reference/refunds/refund#refund-allocation-object) associated with this line item.
    </ParamField>

    <ResponseField name="sales_taxes" type="Array of SalesTax objects">
      <Expandable title="SalesTax properties">
        <ResponseField name="tax_account" type="TaxAccount object">
          <Expandable title="TaxAccount properties">
            Ledger account associated with this tax.

            <ResponseField name="type" type="string">
              Type of tax account object.
            </ResponseField>

            <ResponseField name="name" type="string">
              Name of the tax account, if a name was specified when this line item was created.
            </ResponseField>

            <ResponseField name="id" type="string">
              ID of the tax account if either an account ID was used to create the tax line item or if no tax account was specified.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="amount" type="integer" required="true">
          Amount, in cents, of tax owed.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="discount_amount" type="integer">
      Total discount given to this line item, in cents.
    </ResponseField>

    <ResponseField name="prepayment_account_identifier" type="object">
      A second [Account Identifier](/api-reference/ledger/account-identifier) specifying that this is a prepayment, and which ledger account to use for accrual reporting.
    </ResponseField>

    <ResponseField name="transaction_tags" type="Array of Tags">
      <Expandable title="Tag properties">
        <ResponseField name="id" required="true" type="string">
          Unique identifier for the tag
        </ResponseField>

        <ResponseField name="key" required="true" type="string">
          The tag's key
        </ResponseField>

        <ResponseField name="value" required="true" type="string">
          The tag's value
        </ResponseField>

        <ResponseField name="dimension_display_name" type="string">
          Display name for the tag dimension
        </ResponseField>

        <ResponseField name="value_display_name" type="string">
          Display name for the tag value
        </ResponseField>

        <ResponseField name="dimension_id" required="true" type="string">
          ID of the tag dimension
        </ResponseField>

        <ResponseField name="definition_id" required="true" type="string">
          ID of the tag value definition
        </ResponseField>

        <ResponseField name="created_at" required="true" type="ISO8601 timestamp">
          When the tag was created
        </ResponseField>

        <ResponseField name="updated_at" required="true" type="ISO8601 timestamp">
          When the tag was last updated
        </ResponseField>

        <ResponseField name="deleted_at" type="ISO8601 timestamp">
          When the tag was deleted
        </ResponseField>

        <ResponseField name="archived_at" type="ISO8601 timestamp">
          When the tag was archived
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="subtotal" type="integer" required="true">
  Subtotal of all invoice line items in cents.
</ParamField>

<ParamField body="additional_discount" type="integer">
  Additional discount applied to the whole invoice in addition to individual
  line items.
</ParamField>

<ParamField body="total_discount" type="integer">
  Sum of all discount amounts across the invoice line items and any additional
  discounts in cents.
</ParamField>

<ResponseField name="additional_sales_taxes" type="Array of SalesTax objects">
  <Expandable title="SalesTax properties">
    <ResponseField name="tax_account" type="TaxAccount object">
      <Expandable title="TaxAccount properties">
        Ledger account associated with this tax.

        <ResponseField name="type" type="string">
          Type of tax account object.
        </ResponseField>

        <ResponseField name="name" type="string">
          Name of the tax account, if a name was specified when this line item was created.
        </ResponseField>

        <ResponseField name="id" type="string">
          ID of the tax account if either an account ID was used to create the tax line item or if no tax account was specified.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="amount" type="integer">
      Amount, in cents, of tax owed.
    </ResponseField>
  </Expandable>
</ResponseField>

<ParamField body="total_tax" type="integer">
  Sum of all taxes across the invoice line items and any additional taxes in
  cents.
</ParamField>

<ParamField body="tips" type="integer">
  Tips included by the buyer, in cents.
</ParamField>

<ParamField body="tips_account" type="object">
  The [Account Identifier](/api-reference/ledger/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.
</ParamField>

<ParamField body="total" type="integer" required="true">
  Total amount of the invoice in cents.
</ParamField>

<ParamField body="outstanding_balance" type="integer" required="true">
  The remaining balance on the invoice after factoring in all previous invoice
  payments and write-offs.
</ParamField>

<ParamField body="memo" type="string">
  Memo for any text you would like to associate with the invoice (for example, to display to end users).
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary custom metadata in JSON format with a size limit of 1KB.
</ParamField>

<ParamField body="reference_number" type="string">
  Any (typically user-visible) identifier you would like to associate with the invoice. Can be used to filter when listing invoices.
</ParamField>

<ResponseField name="transaction_tags" type="Array of Tags">
  <Expandable title="Tag properties">
    <ResponseField name="id" required="true" type="string">
      Unique identifier for the tag
    </ResponseField>

    <ResponseField name="key" required="true" type="string">
      The tag's key
    </ResponseField>

    <ResponseField name="value" required="true" type="string">
      The tag's value
    </ResponseField>

    <ResponseField name="dimension_display_name" type="string">
      Display name for the tag dimension
    </ResponseField>

    <ResponseField name="value_display_name" type="string">
      Display name for the tag value
    </ResponseField>

    <ResponseField name="dimension_id" required="true" type="string">
      ID of the tag dimension
    </ResponseField>

    <ResponseField name="definition_id" required="true" type="string">
      ID of the tag value definition
    </ResponseField>

    <ResponseField name="created_at" required="true" type="ISO8601 timestamp">
      When the tag was created
    </ResponseField>

    <ResponseField name="updated_at" required="true" type="ISO8601 timestamp">
      When the tag was last updated
    </ResponseField>

    <ResponseField name="deleted_at" type="ISO8601 timestamp">
      When the tag was deleted
    </ResponseField>

    <ResponseField name="archived_at" type="ISO8601 timestamp">
      When the tag was archived
    </ResponseField>
  </Expandable>
</ResponseField>

<ParamField body="payment_allocations" type="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`.

  <Expandable title="InvoicePaymentAllocation properties">
    <ResponseField name="invoice_id" type="string">
      ID of the invoice.
    </ResponseField>

    <ResponseField name="payment_id" type="string" required="true">
      ID of the payment.
    </ResponseField>

    <ResponseField name="amount" type="integer" required="true">
      Amount of the payment allocated towards this invoice. If this amount is the full payment amount,
      this payment was fully allocated towards this invoice.
      The amount cannot exceed the invoice total.
    </ResponseField>

    <ResponseField name="payment" type="InvoicePayment">
      The [Invoice Payment](/api-reference/invoice/payments) that was allocated towards this invoice.
    </ResponseField>

    <ResponseField name="transaction_tags" type="Array of Tags">
      <Expandable title="Tag properties">
        <ResponseField name="id" required="true" type="string">
          Unique identifier for the tag
        </ResponseField>

        <ResponseField name="key" required="true" type="string">
          The tag's key
        </ResponseField>

        <ResponseField name="value" required="true" type="string">
          The tag's value
        </ResponseField>

        <ResponseField name="dimension_display_name" type="string">
          Display name for the tag dimension
        </ResponseField>

        <ResponseField name="value_display_name" type="string">
          Display name for the tag value
        </ResponseField>

        <ResponseField name="dimension_id" required="true" type="string">
          ID of the tag dimension
        </ResponseField>

        <ResponseField name="definition_id" required="true" type="string">
          ID of the tag value definition
        </ResponseField>

        <ResponseField name="created_at" required="true" type="ISO8601 timestamp">
          When the tag was created
        </ResponseField>

        <ResponseField name="updated_at" required="true" type="ISO8601 timestamp">
          When the tag was last updated
        </ResponseField>

        <ResponseField name="deleted_at" type="ISO8601 timestamp">
          When the tag was deleted
        </ResponseField>

        <ResponseField name="archived_at" type="ISO8601 timestamp">
          When the tag was archived
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="write_offs" type="array of Invoice Write-Off objects">
  Write-offs applied to the invoice. See the [Write-Off object](/api-reference/v1/fetch-write-off) for more information.

  <Expandable title="Invoice Write-Off properties">
    <ResponseField name="id" required="true" type="string">
      Unique identifier for the write-off.
    </ResponseField>

    <ResponseField name="invoice_id" required="true" type="string">
      Unique identifier for the invoice the write-off is for.
    </ResponseField>

    <ResponseField name="external_id" type="string">
      Unique ID of the write-off in your system for linking and idempotency.
    </ResponseField>

    <ResponseField name="amount" required="true" type="long">
      The amount written off. This amount counts towards the invoice total and decreases the outstanding balance of the invoice.
    </ResponseField>

    <ResponseField name="memo" type="string">
      User-specified memo indicating the reason for the write-off.
    </ResponseField>

    <ResponseField name="destination_ledger_account" required="true" type="Ledger Accuont">
      Expense account where write off amount is recorded.
    </ResponseField>

    <ResponseField name="write_off_at" required="true" type="ISO8601 timestamp">
      Timestamp when the write off should be recognized in the general ledger.
      This may be the same time as the invoice was created if it is an intentional charitable contribution or it could be months after the invoice is issued when that invoice is deemed uncollectible.
    </ResponseField>
  </Expandable>

  <ResponseField name="transaction_tags" type="Array of Tags">
    <Expandable title="Tag properties">
      <ResponseField name="id" required="true" type="string">
        Unique identifier for the tag
      </ResponseField>

      <ResponseField name="key" required="true" type="string">
        The tag's key
      </ResponseField>

      <ResponseField name="value" required="true" type="string">
        The tag's value
      </ResponseField>

      <ResponseField name="dimension_display_name" type="string">
        Display name for the tag dimension
      </ResponseField>

      <ResponseField name="value_display_name" type="string">
        Display name for the tag value
      </ResponseField>

      <ResponseField name="dimension_id" required="true" type="string">
        ID of the tag dimension
      </ResponseField>

      <ResponseField name="definition_id" required="true" type="string">
        ID of the tag value definition
      </ResponseField>

      <ResponseField name="created_at" required="true" type="ISO8601 timestamp">
        When the tag was created
      </ResponseField>

      <ResponseField name="updated_at" required="true" type="ISO8601 timestamp">
        When the tag was last updated
      </ResponseField>

      <ResponseField name="deleted_at" type="ISO8601 timestamp">
        When the tag was deleted
      </ResponseField>

      <ResponseField name="archived_at" type="ISO8601 timestamp">
        When the tag was archived
      </ResponseField>
    </Expandable>
  </ResponseField>
</ParamField>

<ParamField body="metadata" type="json object">
  Arbitrary metadata you can include with the invoice
</ParamField>

<ParamField body="imported_at" type="ISO8601 timestamp" required="true">
  Time when the invoice was first imported into Layer. **Eligible sort key.**
</ParamField>

<ParamField body="updated_at" type="ISO8601 timestamp" required="true">
  Time when the invoice was last updated in Layer. **Eligible sort key.**
</ParamField>

<ResponseExample>
  ```json Response theme={null}
  {
    "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": {}
    }
  }
  ```
</ResponseExample>