Create a vendor bill

Operation ID: createVendorBill

Group: Accounting › Vendor Bills

POST /accounting/vendor-bills

Not retry-safe: A write that does not run in its own transaction, so it cannot offer replay; it refuses Idempotency-Key with 400. Retry only on a natural key the endpoint rejects duplicates on.

Creates a vendor bill. The bill is created with its line items, and the response contains only its id. The bill always starts in 'pendingApproval' status. To approve it, use POST accounting/vendor-bills/:id/approve.

If the bill has more lines than your tenant allows in one request, the request fails with TOO_MANY_LINES.

To see the bill, including its vendorBillNumber, use GET accounting/vendor-bills/:id.

Parameters

Name	In	Type	Required	Description
`Api-Version`	header	string · v1	yes	The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`.

Request body

Required, application/json: createVendorBillInput.

Field	Type	Required	Description
`vendorId`	string	yes	The vendor the bill is from. See id on GET accounting/vendors/:id. Example: `"3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45"`.
`entityId`	string	yes	The legal entity the bill is posted under. See id on GET base/entities. Example: `"8f2c1d40-5a6b-4c7d-9e80-1f2a3b4c5d6e"`.
`billNumber`	string	yes	The vendor-issued invoice number, as printed on the bill. It is not unique across vendors. Example: `"INV-88213"`.
`billDate`	date	yes	The date printed on the vendor's invoice. Use format YYYY-MM-DD. Example: `"2026-08-01"`.
`dueDate`	date	yes	The date payment is due. Use format YYYY-MM-DD. Example: `"2026-08-31"`.
`currency`	string	yes	The currency of the bill. Format ISO 4217, for example 'USD'. Governs every line amount and vatAmount, which are decimals. Example: `"EUR"`.
`serviceDate`	date	no	The date the goods or services were delivered. Use format YYYY-MM-DD. Omit to leave it unset. For an entity whose country requires a service date it then defaults to billDate.
`paymentTerms`	string	no	The payment-terms key, for example 'net30', 'net60' or 'dueOnReceipt'. The API does not check it against a list. Omit to inherit 'custom'.
`externalVendorBillId`	string	no	The identifier this bill has in the upstream system that produced it. It is not unique.
`markAsPaid`	boolean	no	Whether to mark the bill paid on creation. Defaults to false.
`origin`	string	no	The source system this record came from, as free-form text, for example 'Ramp'. Omit it and it stays unset. The server does not set a value.
`lines`	array<object>	yes	The line items of the bill, in the order they should appear. At least one is expected. A bill with no lines asks for no expense. Example: `[{"amount":"1200.00","description":"Consulting, August","vatPercentage":"19.00"}]`.
`lines[].amount`	decimal	yes	The total line amount, gross, including VAT where applicable, as a decimal in the bill currency.
`lines[].description`	string	no	A description of the line item, typically copied from the vendor's invoice.
`lines[].accountId`	string	no	The GL expense account this line posts to. See id on GET accounting/accounts/:id.
`lines[].departmentId`	string	no	The department this line is charged to. See id on GET people/departments/:id.
`lines[].businessUnitId`	string	no	The business unit this line is charged to. There is no endpoint for it.
`lines[].crossChargeEntityId`	string	no	The legal entity this line is cross charged to (Charge to). See id on GET base/entities. The line's cost moves to that entity through an intercompany cross charge journal entry. It must differ from entityId, and cross charging must be set up for both entities, or the request fails with CROSS_CHARGE_INVALID.
`lines[].customerId`	string	no	The customer this expense is rebilled to. See id on GET accounting/customers/:id. It is only meaningful alongside billableExpense.
`lines[].vatPercentage`	decimal	no	The VAT rate applied, as a percentage. 19 means 19%, not 0.19.
`lines[].vatAccountId`	string	no	The general ledger account the VAT posts to. See id on GET accounting/accounts/:id.
`lines[].reverseVatAccountId`	string	no	The general ledger account reverse-charge VAT posts to. See id on GET accounting/accounts/:id.
`lines[].vatAmount`	decimal	no	The explicit VAT amount, as a decimal in the bill currency. Omit to derive it from vatPercentage.
`lines[].valueAllocationId`	string	no	The value-allocation rule distributing this line across dimensions. There is no endpoint for it.
`lines[].purchaseOrderLineId`	string	no	The purchase-order line this line is matched against. There is no endpoint for it.
`lines[].billableExpense`	string	no	The billable-expense status for this line. Values include 'yes', 'no' and 'skipped'.
`lines[].lineType`	string	no	The kind of line. Values include 'expense' (a one-time cost) and 'prepaidExpense' (an upfront cost spread over several periods). Defaults to 'expense'.
`lines[].amortizationSchedules`	array<object>	no	The amortization schedules to defer this line over, one per accounting book. Only a line whose lineType is 'prepaidExpense' may carry them. Each schedule starts out not started and begins recognizing once the bill is approved and posts.
`lines[].amortizationSchedules[].bookId`	string	no	The accounting book this schedule posts into. See id on GET accounting/books/:id. Omit it on a single-book entity to use that entity's default transaction book; send one entry per book otherwise. Two entries for the same book are refused with DUPLICATE_AMORTIZATION_BOOK.
`lines[].amortizationSchedules[].deferredAccountId`	string	no	The general ledger account the deferred balance sits on until it is recognized. See id on GET accounting/accounts/:id. Defaults to the line's own accountId.
`lines[].amortizationSchedules[].recognitionAccountId`	string	yes	The general ledger account each installment recognizes the expense into. See id on GET accounting/accounts/:id.
`lines[].amortizationSchedules[].amortizationMethod`	string	yes	How the schedule spreads its total. Values include 'exactDays', 'pointInTime', 'straightLine', 'straightLineProRateFirstLast' and 'usageBased'.
`lines[].amortizationSchedules[].amortizationStartDate`	date	yes	The first day the schedule amortizes over. Format YYYY-MM-DD. It must not be after amortizationEndDate.
`lines[].amortizationSchedules[].amortizationEndDate`	date	yes	The last day the schedule amortizes over, inclusive. Format YYYY-MM-DD.
`lines[].amortizationSchedules[].term`	decimal	yes	The number of months the schedule spreads over. A count, not an amount, so it carries no currency. It is required here, because a schedule without one cannot be turned into installments when the bill posts.
`lines[].amortizationSchedules[].description`	string	no	A note to record against the schedule.
`attachments`	array<object>	no	Files to attach to the bill. Each names an already-uploaded file by its id.
`attachments[].fileName`	string	yes	The display name of the attached file.
`attachments[].fileId`	string	yes	The identifier of the already-uploaded file. There is no endpoint for it.

{
  "vendorId": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45",
  "entityId": "8f2c1d40-5a6b-4c7d-9e80-1f2a3b4c5d6e",
  "billNumber": "INV-88213",
  "billDate": "2026-08-01",
  "dueDate": "2026-08-31",
  "currency": "EUR",
  "serviceDate": "2026-01-15",
  "paymentTerms": "<paymentTerms>",
  "externalVendorBillId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "markAsPaid": true,
  "origin": "<origin>",
  "lines": [
    {
      "amount": "1200.00",
      "description": "Consulting, August",
      "vatPercentage": "19.00"
    }
  ],
  "attachments": [
    {
      "fileName": "<fileName>",
      "fileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ]
}

Response

200 Success

Under data (createVendorBillOutput):

Field	Type	Required	Description
`id`	string	yes	The unique identifier for the created vendor bill. Example: `"c41d0b58-2e97-4f6a-8d13-7b5e9c204af6"`.

{
  "data": {
    "id": "c41d0b58-2e97-4f6a-8d13-7b5e9c204af6"
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Errors

Code	Status
`REFERENCE_NOT_FOUND`	400
`ACCOUNT_ENTITY_MISMATCH`	400
`CROSS_CHARGE_INVALID`	400
`TOO_MANY_LINES`	400
`AMORTIZATION_NOT_ALLOWED_ON_LINE`	400
`AMORTIZATION_DATE_RANGE_INVALID`	400
`AMORTIZATION_BOOK_NOT_CONFIGURED`	400
`DUPLICATE_AMORTIZATION_BOOK`	400
`AMORTIZATION_TERM_MISMATCH`	400
`AMORTIZATION_METHOD_INVALID`	400
`AMORTIZATION_SCHEDULE_NOT_FOUND`	400
`AMORTIZATION_SCHEDULE_POSTED`	400
`IDEMPOTENCY_NOT_SUPPORTED`	400

Statuses

400 — Invalid request or business failure. Codes: REFERENCE_NOT_FOUND, ACCOUNT_ENTITY_MISMATCH, CROSS_CHARGE_INVALID, TOO_MANY_LINES, AMORTIZATION_NOT_ALLOWED_ON_LINE, AMORTIZATION_DATE_RANGE_INVALID, AMORTIZATION_BOOK_NOT_CONFIGURED, DUPLICATE_AMORTIZATION_BOOK, AMORTIZATION_TERM_MISMATCH, AMORTIZATION_METHOD_INVALID, AMORTIZATION_SCHEDULE_NOT_FOUND, AMORTIZATION_SCHEDULE_POSTED. Sending an Idempotency-Key is answered with IDEMPOTENCY_NOT_SUPPORTED: this action does not run in its own transaction, so the replay guarantee cannot be offered and the header is refused rather than ignored.
401 — The request carries no valid access token.
403 — Not authorized
404 — Not found
429 — Too many requests from this client address. The response has no body and no Retry-After header.
500 — Internal server error