Bill

A vendor invoice for goods or services received against a purchase order.

billNumberstring

Human-readable bill identifier displayed in Keychain OS.

Example: BILL-2025-0031

vendorInvoiceNumberstring

The vendor's own invoice/reference number.

Example: VND-INV-88421

purchaseOrderNumberstring

The purchase order this bill is against.

Example: PO-2025-0471

vendorNamestring

Display name of the vendor.

Example: Pacific Ingredients Co.

statusstring

Current status of the bill: draft — created, not yet sent. sent — submitted for vendor review. accepted — vendor confirmed. rejected — vendor rejected (see rejection reason). partially_paid — partial payment recorded. fully_paid — fully settled. archived — filed away.

Possible values: [draft, sent, accepted, rejected, partially_paid, fully_paid, archived]

Example: accepted

invoiceDatestring<date>

Date the vendor issued the bill (ISO 8601).

Example: 2025-03-10

dueDatestring<date>

Payment due date (ISO 8601).

Example: 2025-04-09

paymentTermsstring

Payment terms.

Example: Net 30

currencystring

Three-letter currency code (ISO 4217).

Example: USD

subtotalnumber

Sum of all line item totals before tax.

Example: 2800

taxTotalnumber

Total tax amount.

Example: 224

totalAmountnumber

Final amount owed (subtotal + tax).

Example: 3024

paidAmountnumber

Amount already paid. 0 if unpaid.

Example: 0

paymentMethodstring

Payment method, if recorded.

Example: bank_transfer

notesstring

Free-text notes attached to the bill.

lineItems object[]

The line items on this bill.

Array [

lineTypestring

Type of charge.

Possible values: [item, freight, tax, discount, service, misc]

Example: item

skuCodestring

Product code (primarily for item type lines).

Example: 2087

descriptionstring

Line item description.

Example: Organic Tahini

quantitynumber

Quantity billed.

Example: 200

unitOfMeasurestring

Unit of measure.

Example: lbs

unitPricenumber

Price per unit.

Example: 3.25

taxRatenumber

Tax rate as a decimal (e.g., 0.08 for 8%).

Example: 0.08

taxAmountnumber

Tax amount for this line.

Example: 52

lineAmountnumber

Line total.

Example: 650

]

Bill

{
  "billNumber": "BILL-2025-0031",
  "vendorInvoiceNumber": "VND-INV-88421",
  "purchaseOrderNumber": "PO-2025-0471",
  "vendorName": "Pacific Ingredients Co.",
  "status": "accepted",
  "invoiceDate": "2025-03-10",
  "dueDate": "2025-04-09",
  "paymentTerms": "Net 30",
  "currency": "USD",
  "subtotal": 2800,
  "taxTotal": 224,
  "totalAmount": 3024,
  "paidAmount": 0,
  "paymentMethod": "bank_transfer",
  "notes": "string",
  "lineItems": [
    {
      "lineType": "item",
      "skuCode": "2087",
      "description": "Organic Tahini",
      "quantity": 200,
      "unitOfMeasure": "lbs",
      "unitPrice": 3.25,
      "taxRate": 0.08,
      "taxAmount": 52,
      "lineAmount": 650
    }
  ]
}