> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://api-docs.papertracc.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api-docs.papertracc.com/_mcp/server. # Update Bill PATCH https://api.papertracc.com/v1/bills/{id} Content-Type: application/json Updates a bill. Sending `payment_term_id` rebuilds `payment_schedule` from that term. Sending a `due_date` different from the current one replaces the term with that fixed date and clears `payment_schedule`. Requires the `can_modify_bill` permission on the key owner's role. **Keys:** secret key only. Reference: https://api-docs.papertracc.com/core/purchases/bills/update-bill ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. - `identity` header (required) — The identity for the active workspace. ## Servers - `https://api.papertracc.com/v1` (Production, default) - `https://api.papertracc.com/rc-1` (Release Candidate 1) ## Request ### Path parameters - `id` (string, required) ### Body (application/json) This endpoint expects an object. - `items` (list of BillsIdPatchRequestBodyContentApplicationJsonSchemaItemsItems, optional) - `due_date` (datetime, optional) - `payment_term_id` (string, optional) — Payment term to apply. Takes precedence over `due_date`. The document's due dates and any early-payment discount are worked out from the term and returned in `payment_schedule`. - `bill_date` (datetime, optional) - `adjustments` (list of BillsIdPatchRequestBodyContentApplicationJsonSchemaAdjustmentsItems, optional) — Replaces the adjustments on the bill. Send an empty array to remove them all, or leave the field out to keep the current adjustments. - `account_number` (string, optional) - `exchange_rate` (double, optional) ## Response ### 200 OK - `data` (BillsIdPatchResponsesContentApplicationJsonSchemaData, required) - `status` (boolean, required) - `message` (string, required) ## Errors ### 401 Unauthorized Error The API key is missing or invalid, the key owner is no longer an active member of the organisation, or the key owner is not a member of the workspace in the `identity` header. - `status` (boolean, required) - `message` (string, required) - `error_code` (enum, optional) — Machine-readable reason. Present on 402 and 403 responses. - Allowed values: `PERMISSION_DENIED`, `SERVICE_DISABLED`, `OPEN_API_NOT_ENABLED` - `permission` (string, optional) — The role permission the request needs. Set when `error_code` is `PERMISSION_DENIED`. - `service` (string, optional) — The workspace service that is turned off. Set when `error_code` is `SERVICE_DISABLED`. ### 402 Payment Required Error The workspace's subscription plan does not include the Open API. - `status` (boolean, required) - `message` (string, required) - `error_code` (enum, optional) — Machine-readable reason. Present on 402 and 403 responses. - Allowed values: `PERMISSION_DENIED`, `SERVICE_DISABLED`, `OPEN_API_NOT_ENABLED` - `permission` (string, optional) — The role permission the request needs. Set when `error_code` is `PERMISSION_DENIED`. - `service` (string, optional) — The workspace service that is turned off. Set when `error_code` is `SERVICE_DISABLED`. ### 403 Forbidden Error Either the key owner's role does not include the permission this endpoint needs (`PERMISSION_DENIED`), or the service this endpoint belongs to is turned off for the workspace (`SERVICE_DISABLED`). - `status` (boolean, required) - `message` (string, required) - `error_code` (enum, optional) — Machine-readable reason. Present on 402 and 403 responses. - Allowed values: `PERMISSION_DENIED`, `SERVICE_DISABLED`, `OPEN_API_NOT_ENABLED` - `permission` (string, optional) — The role permission the request needs. Set when `error_code` is `PERMISSION_DENIED`. - `service` (string, optional) — The workspace service that is turned off. Set when `error_code` is `SERVICE_DISABLED`. ## Types ### BillsIdPatchRequestBodyContentApplicationJsonSchemaItemsItems - `rate` (double, required) — Price of one unit. Use 0 for a free line. A negative rate is rejected. - `detail` (string, required) - `quantity` (double, required) — Quantity of the line. Must be greater than zero. Fractional quantities are accepted to 4 decimal places and anything finer is rounded. When `sku` points at an item sold `EACH`, the quantity must be a whole number. - `currency_code` (string, required) - `amount` (double, optional) - `tax_id` (string, optional) - `unit` (string, optional) — Unit the line is billed in, for example `CARTON`. Optional, at most 50 characters. When `sku` points at an item that has a selling unit and this is omitted or matches it, the selling unit is used and `quantity` follows that unit's rules. A different unit is kept as sent. - `unit_factor` (double, optional) — How many of the item's stock units one billed unit holds, for example `12` when billing by the carton for an item stocked each. Optional, must be greater than zero, and is kept to 4 decimal places. Treated as 1 when omitted. `quantity` multiplied by `unit_factor` is the stock quantity the line represents. - `account_id` (string, optional) - `sku` (string, optional) — SKU of an inventory item. The line is tied to that item and takes its account, tax and selling unit. Rejected with 404 when no item has this SKU. - `vat` (string, optional) - `vat_rate` (double, optional) - `vendor_id` (string, optional) - `dynamic_fields` (BillsIdPatchRequestBodyContentApplicationJsonSchemaItemsItemsDynamicFields, optional) ### BillsIdPatchRequestBodyContentApplicationJsonSchemaAdjustmentsItems - `name` (string, required) - `type` (string, required) - `value` (double, required) - `amount` (double, required) - `operation` (string, required) - `account_id` (string, required) ### BillsIdPatchResponsesContentApplicationJsonSchemaData - `id` (string, required) - `items` (list of BillsIdPatchResponsesContentApplicationJsonSchemaDataItemsItems, required) - `amount` (string, required) - `status` (string, required) - `vendor` (BillsIdPatchResponsesContentApplicationJsonSchemaDataVendor, required) - `approval` (integer, required) - `due_date` (datetime, required) - `approvals` (list of any, required) - `bill_date` (datetime, required) - `documents` (list of any, required) - `account_id` (string, required) - `created_at` (datetime, required) - `project_id` (string, required) - `adjustments` (list of BillsIdPatchResponsesContentApplicationJsonSchemaDataAdjustmentsItems, required) - `payment_schedule` (PaymentSchedule, required, nullable) — The payment schedule built from the document's payment term, or null when the document has a plain due date. - `prepared_by` (string, required) - `currency_code` (string, required) - `exchange_rate` (string, required) - `bill_reference` (string, required) - `journal_status` (string, required) - `payment_status` (enum, optional) — How far the document has been settled, derived from amount and total_paid. Independent of status, which tracks the document workflow - a sent invoice that is part paid stays SENT with a payment_status of PARTIAL. - Allowed values: `UNPAID`, `PARTIAL`, `PAID` - `journal_entry_id` (any, optional) ### BillsIdPatchRequestBodyContentApplicationJsonSchemaItemsItemsDynamicFields ### BillsIdPatchResponsesContentApplicationJsonSchemaDataItemsItems - `rate` (string, required) — Decimal value serialized as a string, e.g. "12.50". - `amount` (string, required) — Decimal value serialized as a string, e.g. "12.50". - `detail` (string, required) - `tax_id` (string, required) - `quantity` (double, required) — Quantity of the line, as a number with at most 4 decimal places. - `account_id` (string, required) - `inventory_id` (string, required) - `currency_code` (string, required) - `sku` (string, optional) — SKU of the inventory item the line is tied to. Empty when the line was created without a `sku`. - `tax_name` (string, optional) - `vat` (string, optional) - `unit` (string, optional) — Unit of measure for the line: the item's selling unit (`EACH`, `G`, `KG`, `OZ`, `LB`, `ML`, `L`, `FL_OZ`, `CM`, `M`, `IN`, `FT`, `YD`) or the label sent on the request. Omitted when the line has no unit. - `unit_factor` (string, optional) — Stock units held by one billed unit. Decimal value serialized as a string. Omitted when no factor was sent, in which case it is 1. ### BillsIdPatchResponsesContentApplicationJsonSchemaDataVendor - `id` (string, required) - `display_name` (string, required) ### BillsIdPatchResponsesContentApplicationJsonSchemaDataAdjustmentsItems - `name` (string, required) - `type` (string, required) - `value` (string, required) — Decimal value serialized as a string, e.g. "12.50". - `amount` (string, required) — Decimal value serialized as a string, e.g. "12.50". - `operation` (string, required) - `account_id` (string, required) ### PaymentSchedule - `term_id` (string, required, nullable) — The payment term the schedule was built from. - `name` (string, required) — The term name at the time it was applied. - `net_days` (integer, required) - `instalments` (list of PaymentScheduleInstalment, required) — Empty when the document has a single due date, which is then `due_date` on the document. - `discount` (PaymentScheduleDiscount, required, nullable) — Early-payment discount on this document, or null. - `is_layaway` (boolean, optional) — Present and true on a layaway order's schedule. - `release_instalment` (integer, optional) — Present on a layaway order's schedule: the instalment after which the goods are released. ### PaymentScheduleInstalment - `type` (enum, required) — `PERCENTAGE_RATE` reads `value` as a percentage of the document total. `FLAT_RATE` reads it as an amount in the document currency. - Allowed values: `PERCENTAGE_RATE`, `FLAT_RATE` - `value` (string, required) — Decimal value serialized as a string. - `net_days` (integer, required) - `due_date` (datetime, required) — RFC 3339 timestamp. Fractional seconds are present when the underlying value has sub-second precision and are variable-length (not padded to a fixed number of digits) - they may be absent entirely, e.g. 2025-12-29T18:00:00Z, or carry up to 9 digits, e.g. 2025-12-29T18:00:00.610806Z. - `amount` (string, required) — The share of the document total due on `due_date`. Decimal value serialized as a string. ### PaymentScheduleDiscount - `type` (enum, required) — `PERCENTAGE_RATE` reads `value` as a percentage of the document total. `FLAT_RATE` reads it as an amount in the document currency. - Allowed values: `PERCENTAGE_RATE`, `FLAT_RATE` - `value` (string, required) — Decimal value serialized as a string. - `net_days` (integer, required) - `deadline` (datetime, required) — The last day the discount can be taken. - `amount` (string, required) — The discount available on this document. Decimal value serialized as a string. ## Examples **Request** ```json { "items": [ { "rate": 50000, "detail": "Consulting hours", "quantity": 10, "currency_code": "NGN", "amount": 500000, "tax_id": "78c68f6d-d734-4822-9a6c-73f517a0e5c1", "account_id": "d037d299-3029-4dc7-8e72-172f80f23c4f", "sku": "SKU-1001" } ], "due_date": "2026-07-19T10:00:00.000Z", "bill_date": "2026-06-19T10:00:00.000Z", "adjustments": [ { "name": "VAT", "type": "PERCENTAGE_RATE", "value": 7.5, "amount": 37500, "operation": "ADDITION", "account_id": "2b0d1461-e52e-4a1a-a69c-11801431c2c9" } ], "account_number": "0987654321" } ``` **Response** ```json { "data": { "id": "45c6e26d-e132-4548-8e2e-5bfc467cf94a", "items": [ { "rate": "50000.00", "amount": "500000.00", "detail": "Consulting hours", "tax_id": "78c68f6d-d734-4822-9a6c-73f517a0e5c1", "quantity": 10, "account_id": "d037d299-3029-4dc7-8e72-172f80f23c4f", "inventory_id": "55a40b4d-a23a-49aa-a417-828913e9a5c8", "currency_code": "NGN", "sku": "SKU-1001" } ], "amount": "250000.00", "status": "PENDING", "vendor": { "id": "0cb2d1a5-2f50-43a1-8c3f-df06f998ef51", "display_name": "Global Softworks" }, "approval": 0, "due_date": "2026-07-18T10:00:00Z", "approvals": [], "bill_date": "2026-06-18T10:00:00Z", "documents": [], "account_id": "d037d299-3029-4dc7-8e72-172f80f23c4f", "created_at": "2026-06-18T10:00:00Z", "project_id": "spruce-demo", "adjustments": [ { "name": "VAT", "type": "PERCENTAGE_RATE", "value": "7.50", "amount": "37500.00", "operation": "ADDITION", "account_id": "2b0d1461-e52e-4a1a-a69c-11801431c2c9" } ], "payment_schedule": null, "prepared_by": "user-token-hash", "currency_code": "NGN", "exchange_rate": "1.00", "bill_reference": "BILL-0001", "journal_status": "UNPOSTED" }, "status": true, "message": "Successfully updated bill" } ``` **SDK Code** ```python Purchases_Bills_Update Bill_example import requests url = "https://api.papertracc.com/v1/bills/id" payload = { "items": [ { "rate": 50000, "detail": "Consulting hours", "quantity": 10, "currency_code": "NGN", "amount": 500000, "tax_id": "78c68f6d-d734-4822-9a6c-73f517a0e5c1", "account_id": "d037d299-3029-4dc7-8e72-172f80f23c4f", "sku": "SKU-1001" } ], "due_date": "2026-07-19T10:00:00.000Z", "bill_date": "2026-06-19T10:00:00.000Z", "adjustments": [ { "name": "VAT", "type": "PERCENTAGE_RATE", "value": 7.5, "amount": 37500, "operation": "ADDITION", "account_id": "2b0d1461-e52e-4a1a-a69c-11801431c2c9" } ], "account_number": "0987654321" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.patch(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Purchases_Bills_Update Bill_example const url = 'https://api.papertracc.com/v1/bills/id'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"items":[{"rate":50000,"detail":"Consulting hours","quantity":10,"currency_code":"NGN","amount":500000,"tax_id":"78c68f6d-d734-4822-9a6c-73f517a0e5c1","account_id":"d037d299-3029-4dc7-8e72-172f80f23c4f","sku":"SKU-1001"}],"due_date":"2026-07-19T10:00:00.000Z","bill_date":"2026-06-19T10:00:00.000Z","adjustments":[{"name":"VAT","type":"PERCENTAGE_RATE","value":7.5,"amount":37500,"operation":"ADDITION","account_id":"2b0d1461-e52e-4a1a-a69c-11801431c2c9"}],"account_number":"0987654321"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Purchases_Bills_Update Bill_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.papertracc.com/v1/bills/id" payload := strings.NewReader("{\n \"items\": [\n {\n \"rate\": 50000,\n \"detail\": \"Consulting hours\",\n \"quantity\": 10,\n \"currency_code\": \"NGN\",\n \"amount\": 500000,\n \"tax_id\": \"78c68f6d-d734-4822-9a6c-73f517a0e5c1\",\n \"account_id\": \"d037d299-3029-4dc7-8e72-172f80f23c4f\",\n \"sku\": \"SKU-1001\"\n }\n ],\n \"due_date\": \"2026-07-19T10:00:00.000Z\",\n \"bill_date\": \"2026-06-19T10:00:00.000Z\",\n \"adjustments\": [\n {\n \"name\": \"VAT\",\n \"type\": \"PERCENTAGE_RATE\",\n \"value\": 7.5,\n \"amount\": 37500,\n \"operation\": \"ADDITION\",\n \"account_id\": \"2b0d1461-e52e-4a1a-a69c-11801431c2c9\"\n }\n ],\n \"account_number\": \"0987654321\"\n}") req, _ := http.NewRequest("PATCH", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Purchases_Bills_Update Bill_example require 'uri' require 'net/http' url = URI("https://api.papertracc.com/v1/bills/id") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Patch.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"items\": [\n {\n \"rate\": 50000,\n \"detail\": \"Consulting hours\",\n \"quantity\": 10,\n \"currency_code\": \"NGN\",\n \"amount\": 500000,\n \"tax_id\": \"78c68f6d-d734-4822-9a6c-73f517a0e5c1\",\n \"account_id\": \"d037d299-3029-4dc7-8e72-172f80f23c4f\",\n \"sku\": \"SKU-1001\"\n }\n ],\n \"due_date\": \"2026-07-19T10:00:00.000Z\",\n \"bill_date\": \"2026-06-19T10:00:00.000Z\",\n \"adjustments\": [\n {\n \"name\": \"VAT\",\n \"type\": \"PERCENTAGE_RATE\",\n \"value\": 7.5,\n \"amount\": 37500,\n \"operation\": \"ADDITION\",\n \"account_id\": \"2b0d1461-e52e-4a1a-a69c-11801431c2c9\"\n }\n ],\n \"account_number\": \"0987654321\"\n}" response = http.request(request) puts response.read_body ``` ```java Purchases_Bills_Update Bill_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.patch("https://api.papertracc.com/v1/bills/id") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"items\": [\n {\n \"rate\": 50000,\n \"detail\": \"Consulting hours\",\n \"quantity\": 10,\n \"currency_code\": \"NGN\",\n \"amount\": 500000,\n \"tax_id\": \"78c68f6d-d734-4822-9a6c-73f517a0e5c1\",\n \"account_id\": \"d037d299-3029-4dc7-8e72-172f80f23c4f\",\n \"sku\": \"SKU-1001\"\n }\n ],\n \"due_date\": \"2026-07-19T10:00:00.000Z\",\n \"bill_date\": \"2026-06-19T10:00:00.000Z\",\n \"adjustments\": [\n {\n \"name\": \"VAT\",\n \"type\": \"PERCENTAGE_RATE\",\n \"value\": 7.5,\n \"amount\": 37500,\n \"operation\": \"ADDITION\",\n \"account_id\": \"2b0d1461-e52e-4a1a-a69c-11801431c2c9\"\n }\n ],\n \"account_number\": \"0987654321\"\n}") .asString(); ``` ```php Purchases_Bills_Update Bill_example request('PATCH', 'https://api.papertracc.com/v1/bills/id', [ 'body' => '{ "items": [ { "rate": 50000, "detail": "Consulting hours", "quantity": 10, "currency_code": "NGN", "amount": 500000, "tax_id": "78c68f6d-d734-4822-9a6c-73f517a0e5c1", "account_id": "d037d299-3029-4dc7-8e72-172f80f23c4f", "sku": "SKU-1001" } ], "due_date": "2026-07-19T10:00:00.000Z", "bill_date": "2026-06-19T10:00:00.000Z", "adjustments": [ { "name": "VAT", "type": "PERCENTAGE_RATE", "value": 7.5, "amount": 37500, "operation": "ADDITION", "account_id": "2b0d1461-e52e-4a1a-a69c-11801431c2c9" } ], "account_number": "0987654321" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Purchases_Bills_Update Bill_example using RestSharp; var client = new RestClient("https://api.papertracc.com/v1/bills/id"); var request = new RestRequest(Method.PATCH); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"items\": [\n {\n \"rate\": 50000,\n \"detail\": \"Consulting hours\",\n \"quantity\": 10,\n \"currency_code\": \"NGN\",\n \"amount\": 500000,\n \"tax_id\": \"78c68f6d-d734-4822-9a6c-73f517a0e5c1\",\n \"account_id\": \"d037d299-3029-4dc7-8e72-172f80f23c4f\",\n \"sku\": \"SKU-1001\"\n }\n ],\n \"due_date\": \"2026-07-19T10:00:00.000Z\",\n \"bill_date\": \"2026-06-19T10:00:00.000Z\",\n \"adjustments\": [\n {\n \"name\": \"VAT\",\n \"type\": \"PERCENTAGE_RATE\",\n \"value\": 7.5,\n \"amount\": 37500,\n \"operation\": \"ADDITION\",\n \"account_id\": \"2b0d1461-e52e-4a1a-a69c-11801431c2c9\"\n }\n ],\n \"account_number\": \"0987654321\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Purchases_Bills_Update Bill_example import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "items": [ [ "rate": 50000, "detail": "Consulting hours", "quantity": 10, "currency_code": "NGN", "amount": 500000, "tax_id": "78c68f6d-d734-4822-9a6c-73f517a0e5c1", "account_id": "d037d299-3029-4dc7-8e72-172f80f23c4f", "sku": "SKU-1001" ] ], "due_date": "2026-07-19T10:00:00.000Z", "bill_date": "2026-06-19T10:00:00.000Z", "adjustments": [ [ "name": "VAT", "type": "PERCENTAGE_RATE", "value": 7.5, "amount": 37500, "operation": "ADDITION", "account_id": "2b0d1461-e52e-4a1a-a69c-11801431c2c9" ] ], "account_number": "0987654321" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.papertracc.com/v1/bills/id")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PATCH" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```