Skip to main content
POST
https://sandbox.layerfi.com
/
v1
/
businesses
/
{business_id}
/
invoices
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"
      }
    ]
  }'

{
  "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.
​
additional_discount
integer
Additional discount applied to the whole invoice in addition to individual line items.
​
additional_sales_taxes
array of TaxLineItem objects
List of sales tax obligations on this line item.
​
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.
​
tags
array of TagKeyValue objects
​
metadata
json object
Arbitrary metadata you can include with the invoice

​
Response

Returns the created Invoice Object 
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"
      }
    ]
  }'

{
  "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
​
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