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

# Create an Invoice

> This endpoint imports an invoice for a business into Layer.

### Path Parameters

<ParamField path="business_id" type="string">
  ID of the [Business](/api-reference/business/business) the invoice is associated with.
</ParamField>

### Body

<ParamField body="external_id" required="true" type="string">
  External ID for the invoice within your platform. **Idempotency key.**
</ParamField>

<ParamField body="sent_at" required="true" type="ISO8601 timestamp">
  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="voided_at" type="ISO8601 timestamp">
  When the invoice was voided. Voiding excludes the invoice entirely from accounting.
</ParamField>

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

<ParamField body="customer_id" type="string">
  ID of the [Customer](/api-reference/invoice/customer) the invoice is associated with.
  Either the `customer_id` or the `customer_external_id` must be provided.
</ParamField>

<ParamField body="customer_external_id" type="string">
  External ID of the [Customer](/api-reference/invoice/customer) the invoice is associated with.
  Either the `customer_id` or the `customer_external_id` must be provided.

  A customer does not need to be created before creating an invoice.
  When you provide a customer external id, Layer will create a customer object with the provided external id if it does not already exist.
  Customer details can be updated later using the [Update a customer](/api-reference/invoice/update-customer) endpoint.
</ParamField>

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

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

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

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

    <ResponseField name="account_identifier" type="object">
      The [Account Identifier](/api-reference/ledger/account-identifier) for the line item. If specified, the line item will be attributed to this specific account, typically a product or service revenue account.
      If not specified, the product name will be mapped to a revenue account based on the business or industry's accounting configuration.
    </ResponseField>

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

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

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

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

    <ResponseField name="sales_taxes" type="array of CreateTaxLineItem objects">
      List of sales tax obligations on this line item.

      <Expandable title="CreateTaxLineItem properties">
        <ResponseField name="amount" type="integer" required="true">
          Total tax amount for this line item, in cents.
        </ResponseField>

        <ResponseField name="tax_account" type="Tax Identifier object">
          This object can either be either a `Tax_Name` or an `AccountIdentifier` object.
          An [Account Identifier](/api-reference/ledger/account-identifier) can be used when a known specific ledger account is appropriate for a tax.
          A [Tax Name](/api-reference/types/tax-name) can be used to create and use tax categories dynamically.
        </ResponseField>
      </Expandable>
    </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="tags" type="array of TagKeyValue objects">
      Tag key values associated with this invoice line item.

      <Expandable title="TagKeyValue properties">
        <ResponseField name="key" required="true" type="string">
          The tag dimension key (e.g., "department", "project", "location")
        </ResponseField>

        <ResponseField name="dimension_display_name" type="string">
          Optional display name for the tag dimension. If not specified, `key` will be displayed.
        </ResponseField>

        <ResponseField name="value" required="true" type="string">
          The tag value (e.g., "engineering", "project-alpha", "san-francisco")
        </ResponseField>

        <ResponseField name="value_display_name" type="string">
          Optional display name for the tag value definition. If not specified, `value` will be displayed.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ParamField>

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

<ParamField body="additional_sales_taxes" type="array of CreateTaxLineItem objects">
  List of sales tax obligations on this line item.

  <Expandable title="CreateTaxLineItem properties">
    <ResponseField name="amount" type="integer" required="true">
      Total tax amount for this line item, in cents.
    </ResponseField>

    <ResponseField name="tax_account" type="Tax Identifier object">
      This object can either be either a `Tax_Name` or an `AccountIdentifier` object.
      An [Account Identifier](/api-reference/ledger/account-identifier) can be used when a known specific ledger account is appropriate for a tax.
      A [Tax Name](/api-reference/types/tax-name) can be used to create and use tax categories dynamaically.
    </ResponseField>
  </Expandable>
</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="payments" type="array of InvoicePayment objects">
  Payments that have been made towards the balance of the invoice.

  <Expandable title="InvoicePayment properties">
    <ResponseField name="external_id" type="string">
      External ID for the payment within your platform. **Idempotency key.**
    </ResponseField>

    <ResponseField name="method" type="enum">
      Method used to make the payment.
      Values can be: `CASH`, `CHECK`, `CREDIT_CARD`, `ACH`, `CREDIT_BALANCE`, `OTHER`
    </ResponseField>

    <ResponseField name="fee" type="integer">
      Fee associated with processing a payment, e.g. credit card processing fees, in cents.
    </ResponseField>

    <ParamField body="additional_fees" type="array of InvoicePaymentFee objects">
      <Expandable title="InvoicePaymentFee properties">
        <ParamField body="description" type="string">
          Optional description of the fee.
        </ParamField>

        <ParamField body="account" required="true" type="object">
          The [Account Identifier](/api-reference/ledger/account-identifier) for the fee to be debited.
        </ParamField>

        <ParamField body="fee_amount" required="true" type="integer">
          Amount of the fee in cents.
        </ParamField>

        <ParamField body="is_passed_to_customer" required="true" type="boolean">
          Whether or not the fee is passed to the customer. It is paid by the business otherwise.
        </ParamField>
      </Expandable>
    </ParamField>

    <ResponseField name="processor" type="string">
      Processor used to make the payment, if any.
      Any processor name can be provided and will be tracked.
    </ResponseField>

    <ResponseField name="amount" type="integer">
      Value of the payment, in cents. If blank, this is assumed to be the entire total of the invoice.
    </ResponseField>

    <ParamField body="tags" type="array of TagKeyValue objects">
      Tag key values associated with this invoice.

      <Expandable title="TagKeyValue properties">
        <ParamField body="key" required="true" type="string">
          The tag dimension key (e.g., "department", "project", "location")
        </ParamField>

        <ParamField body="dimension_display_name" type="string">
          Optional display name for the tag dimension. If not specified, `key` will be displayed.
        </ParamField>

        <ParamField body="value" required="true" type="string">
          The tag value (e.g., "engineering", "project-alpha", "san-francisco")
        </ParamField>

        <ParamField body="value_display_name" type="string">
          Optional display name for the tag value definition. If not specified, `value` will be displayed.
        </ParamField>
      </Expandable>
    </ParamField>

    <ResponseField name="metadata" type="json object">
      Arbitrary metadata you can include with the invoice payment
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="tags" type="array of TagKeyValue objects">
  <Expandable title="TagKeyValue properties">
    <ParamField body="key" required="true" type="string">
      The tag dimension key (e.g., "department", "project", "location")
    </ParamField>

    <ParamField body="dimension_display_name" type="string">
      Optional display name for the tag dimension. If not specified, `key` will be displayed.
    </ParamField>

    <ParamField body="value" required="true" type="string">
      The tag value (e.g., "engineering", "project-alpha", "san-francisco")
    </ParamField>

    <ParamField body="value_display_name" type="string">
      Optional display name for the tag value definition. If not specified, `value` will be displayed.
    </ParamField>
  </Expandable>
</ParamField>

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

### Response

Returns the created [Invoice Object](/api-reference/invoice/invoice)

<RequestExample>
  ```bash Request theme={null}
  curl -X POST https://sandbox.layerfi.com/v1/businesses/{business_id}/invoices \
    -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
      "external_id": "019234",
      "sent_at": "2024-04-02T09:02:00Z",
      "due_at": "2023-04-02T09:02:00Z",
      "invoice_number": "1",
      "customer_external_id": "customer-john-doe",
      "line_items": [
        {
          "external_id": "invoice-line-item-1",
          "product": "Cleaner Solution Pro",
          "unit_price": 1299,
          "quantity": 2,
          "sales_taxes": [
            {
              "tax_account": {
                "type": "Tax_Name",
                "name": "CALIFORNIA_VAT"
              },
              "amount": 218
            }
          ],
          "tags": [
            {
              "key": "product-category",
              "dimension_display_name": "Product Category",
              "value": "test-value",
              "value_display_name": "test-display-name"
            }
          ]
        },
        {
          "external_id": "invoice-line-item-2",
          "product": "Full drain cleaning service",
          "unit_price": 25000,
          "quantity": 1,
          "tags": [
            {
              "key": "product-category",
              "dimension_display_name": "Product Category",
              "value": "test-value",
              "value_display_name": "test-display-name"
            },
            {
              "key": "service-type",
              "value": "service-value"
            }
          ]
        }
      ],
      "additional_discount": 250,
      "payments": [
        {
          "external_id": "payment-1",
          "amount": 27466,
          "method": "CREDIT_CARD",
          "processor": "STRIPE",
          "paid_at": "2024-04-02T09:02:00Z",
          "fee": 825,
          "tags": [
            {
              "key": "payment-channel",
              "dimension_display_name": "Payment Channel",
              "value": "online",
              "value_display_name": "Online"
            },
            {
              "key": "department",
              "value": "sales"
            }
          ]
        }
      ],
      "tags": [
        {
          "key": "region",
          "dimension_display_name": "Region",
          "value": "west-coast",
          "value_display_name": "West Coast"
        },
        {
          "key": "customer-segment",
          "value": "enterprise"
        }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "type": "Invoice",
      "id": "6d0c298f-3e4e-4538-9a71-1d5359c22f71",
      "business_id": "83d8fb80-31ee-4d57-b684-44b4aaa5e01f",
      "external_id": "019234",
      "status": "SENT",
      "sent_at": "2024-04-02T09:02:00Z",
      "due_at": "2023-04-02T09:02:00Z",
      "paid_at": null,
      "voided_at": null,
      "invoice_number": "1",
      "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": "e6a491dd-9c22-4403-a54f-32d741a7ec67",
          "external_id": "invoice-line-item-1",
          "invoice_id": "6d0c298f-3e4e-4538-9a71-1d5359c22f71",
          "account_identifier": null,
          "description": null,
          "product": "Cleaner Solution Pro",
          "unit_price": 1299,
          "quantity": "2.00",
          "subtotal": 2598,
          "discount_amount": 0,
          "sales_taxes_total": 218,
          "sales_taxes": [
            {
              "tax_account": {
                "type": "Tax_Name",
                "name": "CALIFORNIA_VAT"
              },
              "amount": 218
            }
          ],
          "total_amount": 2816
        },
        {
          "id": "44f06385-3ef5-4517-8095-eeedaf2054ab",
          "external_id": "invoice-line-item-2",
          "invoice_id": "6d0c298f-3e4e-4538-9a71-1d5359c22f71",
          "account_identifier": null,
          "description": null,
          "product": "Full drain cleaning service",
          "unit_price": 25000,
          "quantity": "1.00",
          "subtotal": 25000,
          "discount_amount": 0,
          "sales_taxes_total": 0,
          "total_amount": 25000
        }
      ],
      "subtotal": 27598,
      "additional_discount": 250,
      "additional_sales_taxes_total": 0,
      "tips": 0,
      "total_amount": 27566,
      "outstanding_balance": 27566,
      "payment_allocations": [],
      "imported_at": "2024-04-19T02:23:59.902537Z",
      "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>

## Optional: Create a Paid invoice

You can specify an invoice as immediately paid by including `InvoicePayment` object(s) in the `payments` field of the invoice. This allows you to create and invoice and specify the full payment information in a single API call.

This is equivalent to creating an invoice and then creating a payment fully allocated to that invoice.

### `InvoicePayment` parameters

<ParamField body="external_id" required="true" type="string">
  External ID for the invoice within your platform. **Idempotency key.**
</ParamField>

<ParamField body="method" required="true" type="enum">
  Method used to make the payment.
  Values can be: `CASH`, `CHECK`, `CREDIT_CARD`, `ACH`, `CREDIT_BALANCE`, `OTHER`
</ParamField>

<ParamField body="fee" type="integer">
  Fee associated with processing a payment, e.g. credit card processing fees, in cents.
</ParamField>

<ParamField body="additional_fees" type="array of InvoicePaymentFee objects">
  <Expandable title="InvoicePaymentFee properties">
    <ParamField body="description" type="string">
      Optional description of the fee.
    </ParamField>

    <ParamField body="account" required="true" type="object">
      The [Account Identifier](/api-reference/ledger/account-identifier) for the fee to be debited.
    </ParamField>

    <ParamField body="fee_amount" required="true" type="integer">
      Amount of the fee in cents.
    </ParamField>

    <ParamField body="is_passed_to_customer" required="true" type="boolean">
      Whether or not the fee is passed to the customer. It is paid by the business otherwise.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField name="processor" type="string">
  Processor used to make the payment, if any.
  Any processor name can be provided and will be tracked.
</ParamField>

<ParamField body="amount" type="integer">
  Value of the payment, in cents. If blank, this is assumed to be the entire total of the invoice.
</ParamField>

<ParamField name="tags" type="array of TagKeyValue objects">
  Tag key values associated with this invoice payment.

  <Expandable title="TagKeyValue properties">
    <ResponseField name="key" required="true" type="string">
      The tag dimension key (e.g., "department", "project", "location")
    </ResponseField>

    <ResponseField name="dimension_display_name" type="string">
      Optional display name for the tag dimension. If not specified, `key` will be displayed.
    </ResponseField>

    <ResponseField name="value" required="true" type="string">
      The tag value (e.g., "engineering", "project-alpha", "san-francisco")
    </ResponseField>

    <ResponseField name="value_display_name" type="string">
      Optional display name for the tag value definition. If not specified, `value` will be displayed.
    </ResponseField>
  </Expandable>
</ParamField>

## Optional: Create refunds with the invoice

This field can be specified when creating an invoice and any of its invoice line items or invoice payments

<ParamField body="dedicated_refunds" type="array of CreateDedicatedRefundParams objects">
  List of [Dedicated Refunds](/api-reference/refunds/refund#create-dedicated-refund-parameters-object) to create with this payment
</ParamField>