Create an Invoice

This endpoint imports an invoice for a business into Layer.

POST /v1/businesses/{business_id}/invoices

Request

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"
      }
    ]
  }'

Response

{
  "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": {}
  }
}

Path Parameters

business_id · string

ID of the Business the invoice is associated with.

Body

external_id · string · required

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

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.

voided_at · ISO8601 timestamp

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

invoice_number · string

Number for the invoice for display to end-users.

customer_id · string

ID of the Customer the invoice is associated with. Either the customer_id or the customer_external_id must be provided.

customer_external_id · string

External ID of the 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 endpoint.

memo · false

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

line_items · array of InvoiceLineItem objects · required

Line items making up the invoice.

Show InvoiceLineItem properties

external_id · string

The external ID of the invoice line item in your system.

description · string

Description of the specific line item.

account_identifier · object

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

product · string

Reference to the product being sold.

quantity · float

Number of units sold.

unit_price · integer

The amount in cents of each unit.

discount_amount · integer

Total discount given to this line item, in cents.

sales_taxes · array of CreateTaxLineItem objects

List of sales tax obligations on this line item.

Show CreateTaxLineItem properties

amount · integer · required

Total tax amount for this line item, in cents.

tax_account · Tax Identifier object

This object can either be either a Tax_Name or an AccountIdentifier object. An Account Identifier can be used when a known specific ledger account is appropriate for a tax. A Tax Name can be used to create and use tax categories dynamically.

prepayment_account_identifier · object

A second Account Identifier specifying that this is a prepayment, and which ledger account to use for accrual reporting.

tags · array of TagKeyValue objects

Tag key values associated with this invoice line item.

Show TagKeyValue properties

key · string · required

The tag dimension key (e.g., “department”, “project”, “location”)

dimension_display_name · string

Optional display name for the tag dimension. If not specified, key will be displayed.

value · string · required

The tag value (e.g., “engineering”, “project-alpha”, “san-francisco”)

value_display_name · string

Optional display name for the tag value definition. If not specified, value will be displayed.

additional_discount · integer

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

additional_sales_taxes · array of CreateTaxLineItem objects

List of sales tax obligations on this line item.

Show CreateTaxLineItem properties

amount · integer · required

Total tax amount for this line item, in cents.

tax_account · Tax Identifier object

This object can either be either a Tax_Name or an AccountIdentifier object. An Account Identifier can be used when a known specific ledger account is appropriate for a tax. A Tax Name can be used to create and use tax categories dynamaically.

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.

payments · array of InvoicePayment objects

Payments that have been made towards the balance of the invoice.

Show InvoicePayment properties

external_id · string

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

method · enum

Method used to make the payment. Values can be: CASH, CHECK, CREDIT_CARD, ACH, CREDIT_BALANCE, OTHER

fee · integer

Fee associated with processing a payment, e.g. credit card processing fees, in cents.

additional_fees · array of InvoicePaymentFee objects

Show InvoicePaymentFee properties

description · string

Optional description of the fee.

account · object · required

The Account Identifier for the fee to be debited.

fee_amount · integer · required

Amount of the fee in cents.

is_passed_to_customer · boolean · required

Whether or not the fee is passed to the customer. It is paid by the business otherwise.

processor · string

Processor used to make the payment, if any. Any processor name can be provided and will be tracked.

amount · integer

Value of the payment, in cents. If blank, this is assumed to be the entire total of the invoice.

tags · array of TagKeyValue objects

Tag key values associated with this invoice.

Show TagKeyValue properties

key · string · required

The tag dimension key (e.g., “department”, “project”, “location”)

dimension_display_name · string

Optional display name for the tag dimension. If not specified, key will be displayed.

value · string · required

The tag value (e.g., “engineering”, “project-alpha”, “san-francisco”)

value_display_name · string

Optional display name for the tag value definition. If not specified, value will be displayed.

metadata · json object

Arbitrary metadata you can include with the invoice payment

tags · array of TagKeyValue objects

Show TagKeyValue properties

key · string · required

The tag dimension key (e.g., “department”, “project”, “location”)

dimension_display_name · string

Optional display name for the tag dimension. If not specified, key will be displayed.

value · string · required

The tag value (e.g., “engineering”, “project-alpha”, “san-francisco”)

value_display_name · string

Optional display name for the tag value definition. If not specified, value will be displayed.

metadata · json object

Arbitrary metadata you can include with the invoice

Response

Returns the created Invoice Object

Request

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"
      }
    ]
  }'

Response

{
  "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": {}
  }
}

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

external_id · string · required

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

method · enum · required

Method used to make the payment. Values can be: CASH, CHECK, CREDIT_CARD, ACH, CREDIT_BALANCE, OTHER

fee · integer

Fee associated with processing a payment, e.g. credit card processing fees, in cents.

additional_fees · array of InvoicePaymentFee objects

Show InvoicePaymentFee properties

description · string

Optional description of the fee.

account · object · required

The Account Identifier for the fee to be debited.

fee_amount · integer · required

Amount of the fee in cents.

is_passed_to_customer · boolean · required

Whether or not the fee is passed to the customer. It is paid by the business otherwise.

amount · integer

Value of the payment, in cents. If blank, this is assumed to be the entire total of the invoice.

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

dedicated_refunds · array of CreateDedicatedRefundParams objects

List of Dedicated Refunds to create with this payment