Create a bill (accounts payable)

Creates a single bill, i.e. an accounts payable record of money the organization owes a vendor, which books the matching journal entries. The bill needs a vendor — a tagged object {"tag": ..., "contents": ...} naming either an existing Books counterparty ({"tag": "counterpartyId", "contents": ...}) or a banking recipient ({"tag": "recipientId", "contents": ...}, resolved to its linked counterparty) — an effectiveDate (the bill date) and dueDate (both YYYY-MM-DD), and at least one line in lines. Each line needs a ledgerId (the expense ledger to book it against, from getBooksLedgers), a description, and an amount in dollars; a line amount may be negative (e.g. a discount); zero-amount lines are ignored, at least one line must be non-zero, and the lines must total more than zero. referenceNumber (e.g. the vendor's bill number) and notes are optional. The response is the created bill: its id, vendor (always a counterparty id), status, amounts (grossAmount, amountPaid, amountOutstanding), lines, and generated journalEntryIds. To make retries safe, send an Idempotency-Key header: a replay with the same key and body returns the original bill rather than creating a duplicate (a reused key with a different body is rejected). Without one, a retry after a timeout can create a second bill. If a request fails with a server error (HTTP 5xx), the bill may already have been created, so a retry with the same key returns 409 (the original attempt is treated as still in progress); check whether the bill exists rather than retrying with a new key, which could create a duplicate. Request errors are returned as an HTTP error status and create nothing: the token lacks the scope to create accrual sources, a line ledger is outside the Books instance or read-only, the vendor counterparty or recipient does not belong to this organization, or the lines fail Teal's validation.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
uuid

The Books instance to act on. Required for agent organization tokens; defaults to the token organization's instance.

Body Params

A request to create a single bill (accounts payable).

date
required

Date the bill is due.

date
required

Effective date of the bill (e.g. the bill date).

lines
array of objects
required
length ≥ 1

Line items for the bill. At least one is required.

lines*

A bill line item to create.

double
required

Amount for this line item. May be negative (e.g. a discount line).
Zero-amount lines are ignored; at least one line must be non-zero, and the
combined total of all lines must be greater than zero (enforced by Teal).

string
required
length between 1 and 1024

Description of the line item. Required and non-empty; leading and trailing
whitespace is stripped.

string
required

The ledger account (expense account) to book this line against.

string | null

Optional notes or memo for the bill.

string
length ≤ 299

Human-readable reference number (e.g. the vendor's bill number). Optional;
an omitted, null, empty, or whitespace-only value is treated as absent, and
leading and trailing whitespace is stripped.

vendor
required

The vendor the bill is owed to.

Headers
string
Responses

400

Invalid body or Idempotency-Key or booksId

Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json