--- title: "Update a bill" method: PATCH path: "/v2/bills/{billId}" --- # Update a bill `PATCH /v2/bills/{billId}` ## Request - Base URL: `https://api.slash.com` - URL: `https://api.slash.com/v2/bills/{billId}` - Auth: API key in header `X-API-Key` Update a bill. Only the fields you send change. Line items and amounts can only change while the bill is `draft` or `rejected`. ## Request body - BillUpdate: Partial update. An omitted field is left unchanged; `null` clears a clearable field. `lineItems`, `tax`, and `discount` are financial fields and are rejected with `bill_amounts_locked` once the bill has a payment that is not canceled or rejected. - `recipientId` string, nullable: The vendor, a recipient. `null` clears it. Changing the vendor also clears `destinationId` unless you send one or the current destination belongs to the new vendor. - `destinationId` string, nullable: The destination the bill should be paid to. `null` clears it. - `ownerUserId` string: The user responsible for the bill. - `invoiceNumber` string, nullable: The vendor's invoice number. `null` clears it. - `invoiceDate` string, date, nullable: Invoice date as `YYYY-MM-DD`. `null` clears it. - `dueDate` string, date, nullable: Due date as `YYYY-MM-DD`. `null` clears it. - `lineItems` BillLineItemUpdate[]: Replaces the line items. Lines sent with an `id` are updated in place; lines without one are appended; existing lines whose ids are omitted are removed. - `id` string: The id of an existing line to change in place. Lines whose ids are omitted from the array are removed. - `name` string, required: What the line is for. - `quantity` number, required: Number of units greater than zero. Fractional quantities are allowed. - `unitAmount` Money, required: A signed monetary amount expressed in minor units. - `amount` integer, required: Amount in the currency's minor units. - `currency` string, required: Uppercase ISO 4217 currency code. - `tax` object: Tax added to the line totals, in the bill's currency. - `amount` integer, required: Amount in the currency's minor units. - `currency` string, required: Uppercase ISO 4217 currency code. - `discount` object: Discount taken off the line totals, in the bill's currency. - `amount` integer, required: Amount in the currency's minor units. - `currency` string, required: Uppercase ISO 4217 currency code. - `notes` string, nullable: Free-text notes. `null` clears them. ## Response `200` The updated bill. - Bill: Money your legal entity owes a vendor. `status` and `amounts.outstanding` are derived from the bill's payments and cannot be set directly. - `id` string, required: Bill id with the `bill_` prefix. - `status` 'draft' | 'pending_approval' | 'rejected' | 'scheduled' | 'payment_pending' | 'paid' | 'payment_failed' | 'partially_paid', required: Derived from the bill's payments. `draft` until a payment exists; `pending_approval` while a payment awaits approval; `rejected` when the latest approval was rejected; `scheduled` when a payment is scheduled; `payment_pending` while a payment is in flight; `partially_paid` when settled payments cover part of the total; `paid` when they cover all of it; `payment_failed` when the latest payment failed or was returned. - `source` 'manual' | 'email' | 'carrier_account' | 'api', required: How the bill entered Slash. `api` for bills created through this API, `manual` for the dashboard, `email` for the accounts-payable inbox, `carrier_account` for bills pulled from a connected carrier portal. Carrier bills are read-only over the API. - `recipientId` string: The vendor, a recipient readable at `GET /v2/recipients/{recipientId}`. - `destinationId` string: The destination the bill is expected to be paid to, readable at `GET /v2/destinations/{destinationId}`. - `ownerUserId` string: The user responsible for the bill. Absent for bills that arrived by email and have not been assigned. - `invoiceNumber` string: The vendor's invoice number. - `invoiceDate` string, date: Invoice date as `YYYY-MM-DD`. - `dueDate` string, date: Due date as `YYYY-MM-DD`. - `currency` string, required: Uppercase ISO 4217 currency code shared by every amount on the bill. - `amounts` object, required: Every amount is in `currency`, in minor units. - `total` Money, required: A signed monetary amount expressed in minor units. - `amount` integer, required: Amount in the currency's minor units. - `currency` string, required: Uppercase ISO 4217 currency code. - `tax` Money, required: A signed monetary amount expressed in minor units. - `amount` integer, required: Amount in the currency's minor units. - `currency` string, required: Uppercase ISO 4217 currency code. - `discount` Money, required: A signed monetary amount expressed in minor units. - `amount` integer, required: Amount in the currency's minor units. - `currency` string, required: Uppercase ISO 4217 currency code. - `outstanding` Money, required: A signed monetary amount expressed in minor units. - `amount` integer, required: Amount in the currency's minor units. - `currency` string, required: Uppercase ISO 4217 currency code. - `lineItems` BillLineItem[], required: Line items in display order. - `id` string, required: Line item id with the `bill_line_item_` prefix. - `name` string, required: What the line is for, as printed on the invoice. - `quantity` number, required: Number of units. Fractional quantities are allowed. - `unitAmount` Money, required: A signed monetary amount expressed in minor units. - `amount` integer, required: Amount in the currency's minor units. - `currency` string, required: Uppercase ISO 4217 currency code. - `total` Money, required: A signed monetary amount expressed in minor units. - `amount` integer, required: Amount in the currency's minor units. - `currency` string, required: Uppercase ISO 4217 currency code. - `documentIds` string[], required: Documents attached to the bill, readable at `GET /v2/documents/{documentId}`. - `payments` BillPayment[], required: Payments linked to the bill, oldest first. - `id` string, required: Payment link id with the `bill_payment_` prefix. Unlink the payment with `DELETE /v2/bills/{billId}/payments/{paymentId}`. - `transferId` string: Id of the transfer that pays the bill, with the `transfer_intent_` prefix, readable at `GET /v2/transfers/{transferId}`. Absent for payments that are not yet a transfer (a scheduled payment whose transfer has not been constructed) or that were made outside the transfer rails. - `transactionId` string: Id of the transaction that moved the money, with the `agg_tx_` prefix, readable at `GET /v2/transactions/{transactionId}`. For a card purchase it's the card transaction. Absent when the payment's only transactions are ones the transactions API doesn't return, such as a rejected or canceled approval request. - `status` 'pending' | 'posted' | 'failed', required: Coarse transaction state. - `detailedStatus` 'pending' | 'pending_destination' | 'pending_approval' | 'in_review' | 'scheduled' | 'canceled' | 'failed' | 'settled' | 'declined' | 'refund' | 'reversed' | 'returned' | 'dispute', required: Exact transaction lifecycle state across every category. - `amount` Money, required: A signed monetary amount expressed in minor units. - `amount` integer, required: Amount in the currency's minor units. - `currency` string, required: Uppercase ISO 4217 currency code. - `createdAt` string, date-time, required: When the payment was linked to the bill. - `notes` string: Free-text notes visible to your organization. - `createdAt` string, date-time, required: When the bill was created. ## Other responses - `400`: - `bill_currency_mismatch` — Every amount on a bill must be in the bill’s `currency`. - `destination_not_vendors` — The destination belongs to a different recipient than the bill’s. - `invalid_request (request shape)` — The body, query, or headers failed validation, or a required header is missing. `details` has one entry per failing location, keyed by JSON pointer or header name. - `401`: - `unauthorized` — API key authentication is missing or invalid. - `403`: - `bill_owner_not_allowed` — This API key can only create and keep bills owned by its own user. - `forbidden` — The credential is not permitted to perform this action on the resource. When the resource is a field of the request, `details` names that `field` and the `id` it received. - `forbidden (legal entity)` — The credential is not permitted to act for the selected legal entity. - `not_available` — Public API v2 is not yet available. Use [Public API v1](https://docs.slash.com/introduction) in the meantime. - `user_api_key_required` — The API key is scoped to a legal entity rather than a user. Every v2 request needs a user API key, created under Settings → API keys in the Slash dashboard, together with the `x-legal-entity` header. - `404`: - `not_found` — No resource matches the identifier. When the identifier is a field of the request, `details` names that `field` and the `id` it received. - `409`: - `bill_amounts_locked` — Amounts can only change while the bill is `draft` or `rejected`. Void the bill to cancel its unsettled payments first. - `carrier_bill_read_only` — The bill was pulled from a connected carrier portal and is managed by that connection. It can be read but not changed. - `429`: The request exceeded the applicable rate limit. The response body is plain text, not the error object; clients must not depend on its wording. - `500`: - `internal` — Slash could not complete the request. Quote `referenceId` when contacting Slash support. ## Changes - **2026-10-16** `8b5d371ffeea`: 1 info - endpoint added [Operation history](https://skmtc.dev/slashfi/apis/slash-public-api/changes/v2/bills/:billId/patch.md) --- [API](https://skmtc.dev/slashfi/apis/slash-public-api.md) - [All operations](https://skmtc.dev/slashfi/apis/slash-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/slashfi/apis/slash-public-api/revisions/eaed2d63c9e2?raw)