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": {}
}
}
Invoices
Create an Invoice
This endpoint imports an invoice for a business into Layer.
POST
/
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
Body
string
required
External ID for the invoice within your platform. Idempotency key.
ISO8601 date or timestamp
required
When the invoice was sent by the business to the recipient. Accepts an ISO 8601 date (
YYYY-MM-DD) or a full ISO 8601 timestamp. A date-only value is stored as midnight Eastern Time on that day.ISO8601 date or timestamp
When the invoice is due. Accepts an ISO 8601 date (
YYYY-MM-DD) or a full ISO 8601 timestamp. A date-only value is stored as midnight Eastern Time on that day.ISO8601 timestamp
When the invoice was voided. Voiding excludes the invoice entirely from accounting.
string
Number for the invoice for display to end-users.
string
ID of the Customer the invoice is associated with.
Either the
customer_id or the customer_external_id must be provided.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.false
Any text you would like to associate with the invoice (for example, to display to end users)
array of InvoiceLineItem objects
required
Line items making up the invoice.
Show InvoiceLineItem properties
Show InvoiceLineItem properties
string
The external ID of the invoice line item in your system.
string
Description of the specific line item.
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.
string
Reference to the product being sold.
float
Number of units sold.
integer
The amount in cents of each unit.
integer
Total discount given to this line item, in cents.
array of CreateTaxLineItem objects
List of sales tax obligations on this line item.
Show CreateTaxLineItem properties
Show CreateTaxLineItem properties
integer
required
Total tax amount for this line item, in cents.
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.object
A second Account Identifier specifying that this is a prepayment, and which ledger account to use for accrual reporting.
array of TagKeyValue objects
Tag key values associated with this invoice line item.
Show TagKeyValue properties
Show TagKeyValue properties
string
required
The tag dimension key (e.g., “department”, “project”, “location”)
string
Optional display name for the tag dimension. If not specified,
key will be displayed.string
required
The tag value (e.g., “engineering”, “project-alpha”, “san-francisco”)
string
Optional display name for the tag value definition. If not specified,
value will be displayed.integer
Additional discount applied to the whole invoice in addition to individual line items.
array of CreateTaxLineItem objects
List of sales tax obligations on this line item.
Show CreateTaxLineItem properties
Show CreateTaxLineItem properties
integer
required
Total tax amount for this line item, in cents.
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.integer
Tips included by the buyer, in cents.
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.
array of InvoicePayment objects
Payments that have been made towards the balance of the invoice.
Show InvoicePayment properties
Show InvoicePayment properties
string
External ID for the payment within your platform. Idempotency key.
enum
Method used to make the payment.
Values can be:
CASH, CHECK, CREDIT_CARD, ACH, CREDIT_BALANCE, OTHERinteger
Fee associated with processing a payment, e.g. credit card processing fees, in cents.
array of InvoicePaymentFee objects
Show InvoicePaymentFee properties
Show InvoicePaymentFee properties
string
Optional description of the fee.
object
required
The Account Identifier for the fee to be debited.
integer
required
Amount of the fee in cents.
boolean
required
Whether or not the fee is passed to the customer. It is paid by the business otherwise.
string
Processor used to make the payment, if any.
Any processor name can be provided and will be tracked.
integer
Value of the payment, in cents. If blank, this is assumed to be the entire total of the invoice.
array of TagKeyValue objects
Tag key values associated with this invoice.
Show TagKeyValue properties
Show TagKeyValue properties
string
required
The tag dimension key (e.g., “department”, “project”, “location”)
string
Optional display name for the tag dimension. If not specified,
key will be displayed.string
required
The tag value (e.g., “engineering”, “project-alpha”, “san-francisco”)
string
Optional display name for the tag value definition. If not specified,
value will be displayed.json object
Arbitrary metadata you can include with the invoice payment
array of TagKeyValue objects
Show TagKeyValue properties
Show TagKeyValue properties
string
required
The tag dimension key (e.g., “department”, “project”, “location”)
string
Optional display name for the tag dimension. If not specified,
key will be displayed.string
required
The tag value (e.g., “engineering”, “project-alpha”, “san-francisco”)
string
Optional display name for the tag value definition. If not specified,
value will be displayed.json object
Arbitrary metadata you can include with the invoice
Response
Returns the created Invoice Objectcurl -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 includingInvoicePayment 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
string
required
External ID for the invoice within your platform. Idempotency key.
enum
required
Method used to make the payment.
Values can be:
CASH, CHECK, CREDIT_CARD, ACH, CREDIT_BALANCE, OTHERinteger
Fee associated with processing a payment, e.g. credit card processing fees, in cents.
array of InvoicePaymentFee objects
Show InvoicePaymentFee properties
Show InvoicePaymentFee properties
string
Optional description of the fee.
object
required
The Account Identifier for the fee to be debited.
integer
required
Amount of the fee in cents.
boolean
required
Whether or not the fee is passed to the customer. It is paid by the business otherwise.
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 paymentsarray of CreateDedicatedRefundParams objects
List of Dedicated Refunds to create with this payment