Bill Pay: Update bills #1771
+224
−5
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,26 @@ | ||
| --- | ||
| title: "Bill Pay: update bills with no hassle" | ||
| date: "2026-02-19" | ||
| tags: ["Product", "Update", "Bill Pay"] | ||
| authors: pzaichkina | ||
| --- | ||
|
|
||
| You can now update existing bills directly through our Bill Pay solution. | ||
|
|
||
| <!--truncate--> | ||
|
|
||
| ## What's new? | ||
|
|
||
| We've expanded our [Bill Pay](/payables/overview) solution with the new [Update bills](/sync-for-payables-v2-api#/operations/update-bill) endpoint. | ||
|
|
||
| No more deleting and recreating bills just to fix a typo or a changed line item. With this update, your customers can edit bills in their accounting software, and we will automatically sync these changes to your platform, keeping the records accurate and up-to-date. | ||
|
|
||
| The endpoint currently supports our FreeAgent, QuickBooks Online, and Xero integrations. | ||
|
|
||
| ## Who is this relevant for? | ||
|
|
||
| This update is relevant for all clients using Codat's Bill Pay solution who want to give their customers a seamless bill management experience. | ||
|
|
||
| ## How to get started? | ||
|
|
||
| You can start using the endpoint right now. Check out the [Update bills](/sync-for-payables-v2-api#/operations/update-bill) endpoint in our API reference, or explore Bill Pay's [Update bills](/payables/sync/update-bill) documentation for a full walkthrough. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,192 @@ | ||
| --- | ||
| title: Update bills | ||
| description: "Update existing bills using Codat's Bill Pay solution" | ||
| sidebar_label: Update a bill | ||
| --- | ||
|
|
||
| import Tabs from "@theme/Tabs"; | ||
|
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶 |
||
| import TabItem from "@theme/TabItem"; | ||
|
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶 |
||
|
|
||
| :::tip Invoices or bills? | ||
|
|
||
| We distinguish between invoices where the company _owes_ money and those where the company _is owed_ money. If the company receives an invoice and owes money as a result, we call this a **bill**. | ||
|
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶 |
||
| ::: | ||
|
|
||
| ## Update a bill | ||
|
|
||
| :::info Software coverage | ||
|
|
||
| This action is currently only supported for FreeAgent, QuickBooks Online, and Xero. | ||
|
|
||
| ::: | ||
|
|
||
| In some cases, your SMB customer may want to update their existing bill: for example, to change a tax rate, change a nominal code for a line item, or associate it to a different supplier. | ||
|
|
||
| Use our [Update bill](/sync-for-payables-v2-api#/operations/update-bill) endpoint to perform this operation. The following rules apply: | ||
|
|
||
| - You can only update the bills in `Open` status, and updates to bills in any other states will be rejected. | ||
|
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶 There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶 |
||
| - During the update, all existing bill line items will removed and replaced with new line items. | ||
|
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶 |
||
| - You can change the following values: | ||
| - `reference` | ||
| - `supplierRef.id` | ||
| - `issueDate` | ||
| - `dueDate` | ||
| - `currency` | ||
| - `currencyRate` | ||
| - `lineItems[]` | ||
|
|
||
| For integration-specific rules and errors, review the [Software requirements](/payables/sync/update-bill#software-requirements) section. | ||
|
|
||
| --- | ||
|
|
||
| ### Example payloads | ||
|
|
||
| <Tabs groupId="software"> | ||
|
|
||
| <TabItem value="gen" label="Request structure"> | ||
|
|
||
| ```json | ||
| PUT /companies/{companyId}/connections/{dataConnectionId}/payables/bills/{billId} | ||
|
|
||
| { | ||
| "reference": "INV-001", | ||
| "supplierRef": { "id": "supplier-id" }, | ||
| "issueDate": "2026-01-28", | ||
| "dueDate": "2026-02-28", | ||
| "currency": "GBP", | ||
| "currencyRate": 1.0, | ||
| "status": "Open", | ||
| "lineItems": [ | ||
| { | ||
| "description": "Service fee", | ||
| "unitAmount": 100.00, | ||
| "quantity": 1, | ||
| "accountRef": { "id": "account-id" }, | ||
| "taxRateRef": { "id": "tax-rate-id" }, | ||
| "taxAmount": 20.00, | ||
| "trackingRefs": [{ "id": "tracking-id" }] | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| </TabItem> | ||
|
|
||
| <TabItem value="fa" label="FreeAgent example"> | ||
|
|
||
| ```json | ||
| { | ||
| "description": "Consulting", | ||
| "unitAmount": 500, | ||
| "quantity": 2, | ||
| "accountRef": { "id": "<nominal-code>" }, | ||
| "taxAmount": 200, | ||
| "trackingRefs": [{ "id": "<project-id>", "isBillable": true }] | ||
| } | ||
| ``` | ||
|
|
||
| </TabItem> | ||
|
|
||
| <TabItem value="qbo" label="QBO example"> | ||
|
|
||
| ```json | ||
| { | ||
| "description": "Consulting", | ||
| "unitAmount": 500, | ||
| "quantity": 2, | ||
| "accountRef": { "id": "<account-id>" }, | ||
| "taxRateRef": { "id": "<tax-rate-id>" } | ||
| } | ||
| ``` | ||
| </TabItem> | ||
|
|
||
| <TabItem value="xero" label="Xero example"> | ||
|
|
||
| ```json | ||
| { | ||
| "description": "Consulting", | ||
| "unitAmount": 500, | ||
| "quantity": 2, | ||
| "accountRef": { "id": "<account-guid>" }, | ||
| "taxRateRef": { "id": "<tax-rate-code>" }, | ||
| "trackingRefs": [{ "id": "<tracking-option-guid>" }] | ||
| } | ||
| ``` | ||
|
|
||
| </TabItem> | ||
|
|
||
| </Tabs> | ||
|
|
||
| ### Software requirements | ||
|
|
||
| We have summarized the key differences between the integrations that support updates to bills below: | ||
|
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶 |
||
|
|
||
| | Feature | FreeAgent | QBO | Xero | | ||
| |--------------------------|----------------------|---------------------|---------------------| | ||
| | **Reference max length** | 255 characters | 21 characters | 255 characters | | ||
| | **`TaxRateRef`** | Must be `null` | Required | Required | | ||
| | **Tax handling** | Use `taxAmount` only | Use `taxRateRef.id` | Use `taxRateRef.id` | | ||
| | **`AccountRef` format** | Nominal code | Numeric string | GUID | | ||
| | **Max line items** | 40 | No limit | No limit | | ||
|
|
||
| ### Validation errors | ||
|
|
||
| You may encounter a validation error when sending a request to update a bill. In the sections below, we`ve included general and software-specific errors to help resolve these. | ||
|
|
||
| #### General validation errors | ||
|
|
||
| | Validation | Error message | | ||
| |-----------------------------|---------------------------------------------------------| | ||
| | Missing `supplierRef` | `Supplier Ref` must not be empty. | | ||
| | Missing `supplierRef.id` | `Supplier Ref Id` must not be empty. | | ||
| | Missing `issueDate` | `Issue Date` must not be empty. | | ||
| | Missing `dueDate` | `Due Date` must not be empty. | | ||
| | Missing currency | `Currency` must not be empty. | | ||
| | Invalid currency | `Currency Length` must be equal to `3`. | | ||
| | Currency rate `<=0` | `Currency Rate` must be greater than `0`. | | ||
| | Missing status | `Status` must not be empty. | | ||
| | Invalid status | `Status` must be equal to `Open`. | | ||
| | Missing or empty line items | `Line Items` must not be empty. | | ||
| | Negative line items total | Sum of `LineItems` must be greater than or equal to `0`. | | ||
| | Reference too long | `Reference Length` must be less than or equal to `255`. | | ||
| | Bill not found | 404 Not Found | | ||
|
|
||
| #### Software-specific errors | ||
|
|
||
| <Tabs groupId="software"> | ||
|
|
||
| <TabItem value="fa" label="FreeAgent"> | ||
|
|
||
| | Issue | Error message | | ||
| |----------------------|-----------------------------------------------| | ||
| | Invalid account code | `Account Ref` was not found in FreeAgent. | | ||
|
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶 |
||
| | Invalid supplier ID | `Supplier Ref Id` was not found in FreeAgent. | | ||
|
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶 |
||
|
|
||
| </TabItem> | ||
|
|
||
| <TabItem value="qbo" label="QuickBooks Online"> | ||
|
|
||
| | Issue | Error message | | ||
| |----------------------------------------|----------------------------------------------------------------------------| | ||
| | Bill currency doesn`t match supplier | Ensure that the currency of the bill matches the currency of the supplier. | | ||
| | Supplier doesn`t support bill currency | The chosen `supplierId` doesn`t handle the bills currency. | | ||
|
|
||
| </TabItem> | ||
|
|
||
| <TabItem value="xero" label="Xero"> | ||
|
|
||
| | Issue | Error message | | ||
| |----------------------|-------------------------------------------| | ||
| | Invalid account GUID | `Account Ref` was not found in Xero. | | ||
|
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶 |
||
| | Invalid supplier ID | `SupplierRef Id` was not found in Xero. | | ||
|
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶 |
||
| | Currency not enabled | No currency exists for code `currency`. | | ||
|
|
||
| </TabItem> | ||
|
|
||
| </Tabs> | ||
|
|
||
| --- | ||
|
|
||
| ## Read next | ||
|
|
||
| - Enable your customers to [pay single bills](/payables/sync/pay-bill) to complete the Bill Pay process. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[Google.WordList] Use 'app' instead of 'application'.