Skip to main content
A Bill represents an invoice or purchase order that a Business has received from a vendor for goods and services. Bills are used to pass information about purchases and accounts payable into Layer.

​
Attributes

​
id
string
required
Unique identifier for the bill.
​
business_id
string
required
ID of the Business that received the bill.
​
external_id
string
Unique ID of the bill in your system for linking purposes.
​
status
enum
required
Status of the bill. Values can be: RECEIVED, PARTIALLY_PAID, PAID, VOIDED
​
terms
enum
required
Payment terms of the bill. Values can be: DUE_ON_RECEIPT, NET_10, NET_15, NET_30, NET_60
​
received_at
ISO8601 timestamp
required
When the bill was received.
​
due_at
ISO8601 timestamp
When the bill is due.
​
paid_at
ISO8601 timestamp
When the bill was paid.
​
voided_at
ISO8601 timestamp
When the bill was voided. Voiding excludes the bill from accounting.
​
vendor
Vendor object
required
The vendor associated with this bill.
​
line_items
array of BillLineItem objects
required
Line items making up the bill.
​
subtotal
integer
required
Subtotal of all bill line items in cents.
​
additional_sales_taxes
Array of TaxLineItem objects
​
additional_sales_taxes_total
integer
Sum of all additional taxes in cents.
​
total_amount
integer
required
Total amount including taxes in cents.
​
outstanding_balance
integer
required
The remaining balance on the bill after factoring in all previous bill payments.
​
memo
string
Memo for any text you would like to associate with the bill (for example, to display to end users).
​
metadata
object
Arbitrary custom metadata in JSON format with a size limit of 1KB.
​
reference_number
string
Any (typically user-visible) identifier you would like to associate with the bill. Can be used to filter when listing bills.
​
payment_allocations
array of BillPaymentAllocation objects
Payments made to a vendor are allocated toward one or many bills. This list shows which payments have been allocated towards this bill. The most common case is that there is a 1:1 relationship between a payment and a bill, in which case the allocation’s amount will match the payment’s amount.
​
vendor_credits
array of VendorCreditAllocation objects
Vendor Credit Allocations towards this bill
​
imported_at
ISO8601 timestamp
required
Time when the bill was first imported into Layer. Eligible sort key.
​
updated_at
ISO8601 timestamp
required
Time when the bill was last updated in Layer. Eligible sort key.
​
transaction_tags
Array of Tags
{
  "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,
    "bill_number": "VB-123",
    "vendor": {
      "id": "a4c38874-8c01-4986-b8d0-4f159a52dd39",
      "external_id": "vendor-1",
      "company_name": "Acme Supplies Inc.",
      "email": "[email protected]",
      "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"
        },
        "description": "Monthly office supplies",
        "product_name": "Paper reams",
        "unit_price": 1500,
        "quantity": "10.00",
        "subtotal": 15000,
        "discount_amount": 1000,
        "sales_taxes_total": 1120,
        "total_amount": 15120
      }
    ],
    "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": "8901-abcd-ef23-4567",
        "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",
          "at": "2024-06-15T00:00:00Z",
          "method": "ACH",
          "amount": 10000,
          "processor": "BANK_TRANSFER",
          "imported_at": "2024-06-15T18:11:57.339076Z",
          "allocations": [
            {
              "id": "8901-abcd-ef23-4567",
              "bill_id": "b745c116-cd28-41a1-b4ea-84a2768b6e14",
              "payment_id": "590ed436-c2bd-4e39-8047-f913a852f99c",
              "amount": 10000,
              "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
                }
              ]
            }
          ],
          "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": {}
        },
        "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": {}
      }
    ],
    "vendor_credits": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "vendor_credit_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "bill_payment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "amount": 123,
          "vendor_credit": {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "external_id": "<string>",
            "vendor": {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "external_id": "<string>",
              "individual_name": "<string>",
              "company_name": "<string>",
              "email": "<string>",
              "mobile_phone": "<string>",
              "office_phone": "<string>",
              "address_string": "<string>",
              "notes": "<string>",
              "status": "ACTIVE",
              "transaction_tags": [
                {
                  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                  "key": "ExampleTagKey",
                  "value": "ExampleTagValue",
                  "created_at": "2023-11-07T05:31:56Z",
                  "updated_at": "2023-11-07T05:31:56Z",
                  "deleted_at": "2023-11-07T05:31:56Z"
                }
              ]
            },
            "received_at": "2023-11-07T05:31:56Z",
            "line_items": [
              {
                "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                "ledger_account": {
                  "id": {
                    "type": "AccountId",
                    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
                  },
                  "name": "Current Assets",
                  "stable_name": {
                    "type": "StableName",
                    "stable_name": "CURRENT_ASSETS"
                  },
                  "normality": "CREDIT",
                  "account_type": {
                    "value": "ASSET",
                    "display_name": "Asset"
                  },
                  "account_subtype": {
                    "value": "CURRENT",
                    "display_name": "Current Assets"
                  }
                },
                "amount": 123,
                "memo": "<string>"
              }
            ],
            "allocations": [
              {
                "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                "vendor_credit_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                "bill_payment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                "amount": 123,
                "metadata": {},
              }
            ],
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "deleted_at": "2023-11-07T05:31:56Z",
            "transaction_tags": [
              {
                "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                "key": "ExampleTagKey",
                "value": "ExampleTagValue",
                "created_at": "2023-11-07T05:31:56Z",
                "updated_at": "2023-11-07T05:31:56Z",
                "deleted_at": "2023-11-07T05:31:56Z"
              }
            ]
          }
        }
      ],
    "imported_at": "2024-06-01T18:11:57.234148Z",
    "updated_at": "2024-06-15T18:11:57.234148Z",
    "transaction_tags": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "key": "Department",
        "value": "Operations",
        "created_at": "2024-06-01T05:31:56Z",
        "updated_at": "2024-06-01T05:31:56Z",
        "deleted_at": null
      }
    ]
  }
}