Skip to main content
POST
/
v1
/
businesses
/
{businessId}
/
bills
Create bill
curl --request POST \
  --url https://sandbox.layerfi.com/v1/businesses/{businessId}/bills \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "received_at": "2023-11-07T05:31:56Z",
  "line_items": [
    {
      "product_name": "<string>",
      "unit_price": 123,
      "external_id": "<string>",
      "account_identifier": {
        "type": "AccountId",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      },
      "prepayment_account_identifier": {
        "id": {
          "type": "AccountId",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        },
        "name": "Current Assets",
        "account_number": "4000",
        "account_type": {
          "display_name": "Asset"
        },
        "account_subtype": {
          "display_name": "Current Assets"
        }
      },
      "description": "<string>",
      "quantity": 1,
      "discount_amount": 123,
      "sales_taxes": [
        {
          "amount": 123,
          "tax_account": {
            "name": "CALIFORNIA_VAT",
            "type": "Tax_Name"
          }
        }
      ],
      "tags": [
        {
          "key": "department",
          "value": "sales",
          "dimension_display_name": "Department",
          "value_display_name": "Sales Department"
        }
      ],
      "memo": "<string>",
      "metadata": {
        "custom_field": "value",
        "any valid json": "below 1kb",
        "nested": {
          "meaning of life": 42,
          "array": []
        }
      },
      "reference_number": "<string>"
    }
  ],
  "external_id": "<string>",
  "due_at": "2023-11-07T05:31:56Z",
  "additional_discount": 0,
  "memo": "<string>",
  "vendor_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "vendor_external_id": "<string>",
  "payments": [
    {
      "amount": 123,
      "external_id": "<string>",
      "processor": "<string>",
      "payment_clearing_account_identifier": {
        "type": "AccountId",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      },
      "tags": [
        {
          "key": "department",
          "value": "sales",
          "dimension_display_name": "Department",
          "value_display_name": "Sales Department"
        }
      ],
      "memo": "<string>",
      "metadata": {
        "custom_field": "value",
        "any valid json": "below 1kb",
        "nested": {
          "meaning of life": 42,
          "array": []
        }
      },
      "reference_number": "<string>"
    }
  ],
  "additional_sales_taxes": [
    {
      "amount": 123,
      "tax_account": {
        "name": "CALIFORNIA_VAT",
        "type": "Tax_Name"
      }
    }
  ],
  "tags": [
    {
      "key": "department",
      "value": "sales",
      "dimension_display_name": "Department",
      "value_display_name": "Sales Department"
    }
  ],
  "is_expense": false,
  "metadata": {
    "custom_field": "value",
    "any valid json": "below 1kb",
    "nested": {
      "meaning of life": 42,
      "array": []
    }
  },
  "reference_number": "<string>"
}
'
{
  "data": {
    "id": "b745c116-cd28-41a1-b4ea-84a2768b6e14",
    "business_id": "188eb399-f171-4849-861c-5c02d91f800b",
    "external_id": "vendor-bill-123",
    "status": "PARTIALLY_PAID",
    "terms": "NET_30",
    "received_at": "2024-06-01T10:11:57.184157Z",
    "due_at": "2024-07-01T10:11:57.184158Z",
    "paid_at": null,
    "voided_at": null,
    "reference_number": "VB-123",
    "vendor": {
      "id": "a4c38874-8c01-4986-b8d0-4f159a52dd39",
      "external_id": "vendor-1",
      "company_name": "Acme Supplies Inc.",
      "email": "billing@acmesupplies.com",
      "office_phone": "555-123-4567",
      "address_string": "123 Vendor St, Supply City, CA 90210",
      "notes": "Primary office supplies vendor",
      "status": "ACTIVE"
    },
    "line_items": [
      {
        "id": "733de30f-db72-4d52-98c5-fe070d4433f7",
        "external_id": "bill-line-item-1",
        "bill_id": "b745c116-cd28-41a1-b4ea-84a2768b6e14",
        "account_identifier": {
          "type": "AccountId",
          "id": "80b708b5-7b27-456c-9fb1-b8b918241908"
        },
        "ledger_account": {
          "id": "80b708b5-7b27-456c-9fb1-b8b918241908",
          "name": "Office Supplies",
          "stable_name": "OFFICE_SUPPLIES",
          "normality": "DEBIT",
          "account_type": {
            "value": "EXPENSE",
            "display_name": "Expenses"
          },
          "account_subtype": {
            "value": "OPERATING_EXPENSES",
            "display_name": "Operating Expenses"
          }
        },
        "description": "Monthly office supplies",
        "product_name": "Paper reams",
        "unit_price": 1500,
        "quantity": "10.00",
        "subtotal": 15000,
        "discount_amount": 1000,
        "sales_taxes_total": 1120,
        "sales_taxes": [
          {
            "tax_account": {
              "type": "Tax_Name",
              "name": "CA_SALES_TAX"
            },
            "tax_ledger_account": {
              "id": "c4007474-f604-4d57-9690-b7f40f7a1cee",
              "name": "Sales tax: CA",
              "stable_name": "SALES_TAXES:CA",
              "normality": "DEBIT",
              "account_type": {
                "value": "EXPENSE",
                "display_name": "Expenses"
              },
              "account_subtype": {
                "value": "SALES_TAXES",
                "display_name": "Sales Taxes"
              }
            },
            "amount": 1120
          }
        ],
        "total_amount": 15120,
        "transaction_tags": [
          {
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "key": "department",
            "value": "operations",
            "dimension_display_name": "Department",
            "value_display_name": "Operations",
            "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
          }
        ]
      }
    ],
    "subtotal": 15000,
    "additional_sales_taxes": [],
    "additional_sales_taxes_total": 0,
    "total_amount": 15120,
    "outstanding_balance": 5120,
    "memo": "Memo for the office supplies purchase",
    "payment_allocations": [
      {
        "id": "8901abcd-ef23-4567-8901-abcd12345678",
        "bill_id": "b745c116-cd28-41a1-b4ea-84a2768b6e14",
        "payment_id": "590ed436-c2bd-4e39-8047-f913a852f99c",
        "amount": 10000,
        "payment": {
          "id": "590ed436-c2bd-4e39-8047-f913a852f99c",
          "external_id": "bill-payment-1",
          "paid_at": "2024-06-15T00:00:00Z",
          "method": "ACH",
          "amount": 10000,
          "processor": "BANK_TRANSFER",
          "imported_at": "2024-06-15T18:11:57.339076Z",
          "allocations": [
            {
              "id": "8901abcd-ef23-4567-8901-abcd12345678",
              "bill_id": "b745c116-cd28-41a1-b4ea-84a2768b6e14",
              "payment_id": "590ed436-c2bd-4e39-8047-f913a852f99c",
              "amount": 10000,
              "transaction_tags": []
            }
          ],
          "transaction_tags": [],
          "memo": "First partial payment",
          "metadata": {},
          "reference_number": "PAY-1001"
        },
        "transaction_tags": [],
        "memo": "Allocated to June office supplies bill",
        "metadata": {},
        "reference_number": "ALLOC-1001"
      }
    ],
    "vendor_credits": [],
    "imported_at": "2024-06-01T10:11:57.184157Z",
    "updated_at": "2024-06-15T18:11:57.339076Z",
    "transaction_tags": [],
    "metadata": {}
  }
}

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.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

businessId
string<uuid>
required

The UUID of the business to create the bill for.

Body

application/json
received_at
string<date-time>
required

When the bill was received by the business from the vendor.

line_items
object[]
required

Line items making up the bill.

external_id
string

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

due_at
string<date-time>

When the bill is due. Either due_at or bill_terms must be specified, but not both.

bill_terms
enum<string>

Payment terms for the bill. Either due_at or bill_terms must be specified, but not both.

Available options:
DUE_ON_RECEIPT,
NET_10,
NET_15,
NET_30,
NET_60
additional_discount
integer<int64> | null
default:0

Additional discount applied to the whole bill in addition to individual line item discounts, in cents.

memo
string

Memo for any text you would like to associate with the bill (for example, to display to end users).

vendor_id
string<uuid>

ID of the vendor to associate with the bill. Either vendor_id or vendor_external_id must be specified.

vendor_external_id
string

External ID of the vendor to associate with the bill. Either vendor_id or vendor_external_id must be specified.

payments
object[]

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

additional_sales_taxes
object[]

Additional sales tax line items for the bill.

tags
object[]
is_expense
boolean
default:false

Whether the bill should be treated as an expense.

metadata
object

Arbitrary custom metadata in JSON format with a size limit of 1KB.

Example:
{
"custom_field": "value",
"any valid json": "below 1kb",
"nested": { "meaning of life": 42, "array": [] }
}
reference_number
string | null

Any (typically user-visible) identifier you would like to associate with the bill. Can be used to filter when listing bills.

Response

201 - application/json

Bill created successfully.

id
string<uuid>

Unique identifier for the bill.

business_id
string<uuid>

ID of the Business that received the bill.

external_id
string | null

Unique ID of the bill in your system.

status
enum<string>

Status of the bill.

Available options:
RECEIVED,
PARTIALLY_PAID,
PAID,
VOIDED
terms
enum<string>

Payment terms of the bill.

Available options:
DUE_ON_RECEIPT,
NET_10,
NET_15,
NET_30,
NET_60
received_at
string<date-time>

When the bill was received.

due_at
string<date-time> | null

When the bill is due.

paid_at
string<date-time> | null

When the bill was paid.

voided_at
string<date-time> | null

When the bill was voided. Voiding excludes the bill from accounting.

memo
string

Memo for the bill for display.

line_items
object[]

Line items making up the bill.

additional_sales_taxes
object[]

Additional sales tax line items.

additional_sales_taxes_total
integer

Sum of all additional taxes in cents.

additional_discount
integer<int64>

Additional discount applied to the whole bill in addition to individual line item discounts, in cents.

subtotal
integer

Subtotal of all line items in cents.

total_amount
integer

Total amount including taxes in cents.

outstanding_balance
integer

Remaining balance after payments in cents.

payment_allocations
object[]

Payments made to a vendor are allocated toward one or many bills. This list shows which payments have been allocated toward this bill. The most common case is a 1:1 relationship between a payment and a bill, in which case the allocation amount matches the payment amount.

vendor_credits
object[]

Vendor credit allocations for this bill.

imported_at
string<date-time>

When the bill was imported. Eligible sort key.

updated_at
string<date-time>

When the bill was last updated. Eligible sort key.

vendor
object

The vendor associated with this bill.

transaction_tags
object[]
is_expense
boolean

Whether the bill is treated as an expense.

metadata
object

Arbitrary custom metadata in JSON format with a size limit of 1KB.

Example:
{
"custom_field": "value",
"any valid json": "below 1kb",
"nested": { "meaning of life": 42, "array": [] }
}
reference_number
string | null

Any (typically user-visible) identifier you would like to associate with the bill. Can be used to filter when listing bills.