Bill Pay: Update supplier

blog/260331-update-suppliers-bill-pay.md

@@ -0,0 +1,26 @@
+---
+title: "Bill Pay: update suppliers with ease"
+date: "2026-03-31"
+tags: ["Product", "Update", "Bill Pay"]
+authors: pzaichkina
+---
+
+You can now update existing suppliers directly through our Bill Pay solution. 
+
+<!--truncate-->
+
+## What's new?
+
+We've expanded our [Bill Pay](/payables/overview) solution with the new [Update suppliers](/sync-for-payables-v2-api#/operations/update-supplier) endpoint. 
+
+With this update, your customers can edit suppliers 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 and supplier management experience.
+
+## How to get started?
+
+You can start using the endpoint right now. Check out the [Update suppliers](/sync-for-payables-v2-api#/operations/update-supplier) endpoint in our API reference, or explore Bill Pay's [Update supplier](/payables/sync/update-supplier) documentation for a full walkthrough.s

docs/payables/_manage-suppliers.md

@@ -155,4 +155,4 @@ supplierCreateResponse, err := payablesClient.Suppliers.Create(ctx, operations.C
 
 </TabItem>
 
-</Tabs>
+</Tabs>

docs/payables/configure-customer.md

@@ -126,34 +126,13 @@ Next, use the [Create connection](/sync-for-payables-v2-api#/operations/create-c
 
 This will allow you to synchronize data with that source, fetching or creating suppliers, bills, and payment methods. In the request body, specify a `platformKey` of the accounting software you're looking to connect.
 
-<Tabs>
-
-<TabItem value="async" label="Async Bill Pay">
-
-| Accounting software | platformKey |
-| ------------------- | ----------- |
-| MYOB Business       | `pdvj`      |
-| Oracle NetSuite     | `akxx`      |
-| QuickBooks Online   | `qhyg`      |
-| QuickBooks Desktop  | `pqsw`      |
-| Sage Intacct        | `knfz`      |
-| Xero                | `gbol`      |
-
-</TabItem>
-
-<TabItem value="sync" label="Sync Bill Pay">
-
 | Accounting software | platformKey |
 | ------------------- | ----------- |
 | FreeAgent           | `fbrh`      |
 | Oracle NetSuite     | `akxx`      |
 | QuickBooks Online   | `qhyg`      |
 | Xero                | `gbol`      |
 
-</TabItem>
-
-</Tabs>
-
 As an example, let's create a QuickBooks Online (QBO) connection. In response, the endpoint returns a `dataConnection` object with a `PendingAuth` status and a `linkUrl`. Direct your customer to the `linkUrl` to initiate our [Link auth flow](/auth-flow/overview) and enable them to authorize this connection.
 
 <Tabs groupId="language">

docs/payables/sync/bills.md

@@ -1,6 +1,6 @@
 ---
 title: Manage bills
-description: "View and create bills using Codat's sync Bill Pay solution"
+description: "View and create bills using Codat's Bill Pay solution"
 sidebar_label: Create a bill
 ---
 
@@ -17,10 +17,11 @@ We distinguish between invoices where the company _owes_ money and those where t
 
 ## Overview
 
-In Codat, a bill represents an _accounts payable_ invoice issued to an SMB by their supplier. With synchronous Bill Pay, you can:
+In Codat, a bill represents an _accounts payable_ invoice issued to an SMB by their supplier. With Bill Pay, you can:
 
 - Retrieve your customer's existing bills.
 - Create new bills in your system and reflect them in your customer's accounting software.
+- Update existing bills and reflect the changes in your customer's accounting software.
 
 We have highlighted this alternative sequence of steps in our detailed process diagram below.
 
@@ -43,6 +44,9 @@ We have highlighted this alternative sequence of steps in our detailed process d
       else Create bill
         app ->> codat: Creates bill
         codat ->> acctg: Creates bill
+      else Update bill
+        app ->> codat: Updates bill
+        codat ->> acctg: Updates bill
       end
 ```
 
@@ -52,7 +56,7 @@ We have highlighted this alternative sequence of steps in our detailed process d
 
 :::tip Filter the bill list
 
-Bill endpoints of the sync Bill Pay solution only return **open** or **partially paid** bills from the accounting platform. You can use [query parameters](/using-the-api/querying) to change the scope of results.
+Bill endpoints of the Bill Pay solution only return **open** or **partially paid** bills from the accounting platform. You can use [query parameters](/using-the-api/querying) to change the scope of results.
 :::
 
 <RetrieveBills

docs/payables/sync/pay-bill.md

@@ -10,7 +10,7 @@ description: "Record and reconcile bill payments in the SMB's accounting softwar
 Finally, your SMB customer will make a payment from your application, which you should then record and reconcile back to the SMB's accounting software. A **bill payment** represents an allocation of money within any of your customer's accounts payable (AP) accounts.
 
 :::tip Bill type coverage
-Our **sync Bill Pay** solution focuses on providing a fast implementation experience and streamlined recording of payments. As a result, it supports payments of **single bills only**.
+Our **Bill Pay** solution focuses on providing a fast implementation experience and streamlined recording of payments. As a result, it supports payments of **single bills only**.
 :::
 
 ## Manage payment accounts
@@ -37,7 +37,7 @@ If the SMB customer plans to make payments from a new payment method or account
 
 :::tip Partial payments
 
-Our sync Bill Pay solution supports payments where a singe bill is paid **in full**. To record a partial payment, use the same endpoint and adjust the values to reflect the amount of the partial payment.
+Our Bill Pay solution supports payments where a singe bill is paid **in full**. To record a partial payment, use the same endpoint and adjust the values to reflect the amount of the partial payment.
 
 :::
 

docs/payables/sync/suppliers.md

@@ -37,21 +37,65 @@ To pay a bill in Bill Pay, you can use your customer's existing suppliers or cre
         smb ->> app: Provides supplier details
         app ->> codat: Creates supplier
         codat ->> acctg: Creates supplier record
+      else Update supplier
+        smb ->> app: Provides updated supplier details
+        app ->> codat: Updates supplier
+        codat ->> acctg: Updates supplier record
       end
 ```
 
 </details>
 
 :::tip Narrow down the supplier list
 
-Supplier endpoints of the sync Bill Pay solution return only **active** suppliers from the accounting platform. You can use [query parameters](/using-the-api/querying) to narrow down the list of results further.
+Supplier endpoints of the Bill Pay solution return only **active** suppliers from the accounting platform. You can use [query parameters](/using-the-api/querying) to narrow down the list of results further.
 :::
 
 <ManageSuppliers
   listendpoint="/sync-for-payables-v2-api#/operations/list-suppliers"
   createendpoint="/sync-for-payables-v2-api#/operations/create-supplier"
 />
 
+## Update supplier
+
+If your customer's existing supplier changes address or business name, you can reflect this change in their accounting software using the [Update supplier](sync-for-payables-v2-api#/operations/update-supplier) endpoint.
+
+Include all fields in the request, even if their values haven't changed. If you leave a field out, its value will be **deleted** from the supplier record.
+
+:::info Software coverage
+
+This action is currently only supported for FreeAgent, QuickBooks Online, and Xero.
+
+:::
+
+### Software-specific behavior
+
+Each accounting software has some limitations when updating suppliers. We've summarized them below.
+
+#### Xero
+
+| Limitation             | Description                                                                                                                                      |
+|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| **Supplier name**      | It's not possible to clear the supplier name. Sending a `null` or `""` value for `supplierName`, or `null` value for both `supplierName` and `contactName` keeps the existing supplier name. |
+| **Duplicate names**    | Supplier names must be unique. Updating a name to match an existing supplier returns a `400` response.                                                        |
+| **Archived suppliers** | It's not possible to update archived suppliers via the Xero API. To unarchive, do it manually in Xero.|                                                 |
+
+#### QuickBooks Online
+
+| Limitation             | Description                                                                                                                                               |
+|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **Supplier name**      | If `supplierName` is `null` in the request, QBO uses the value in `contactName` instead. If both fields are `null`, QBO returns a `400` response.|
+| **Default currency**   | It's not possible to update the supplier's currency. Sending a `defaultCurrency` in the request that differs from the current value results in a `400` response. Send a `null` value to leave it unchanged.                      |
+| **Archived suppliers** | All changes to archived suppliers are ignored. Include `"status": "Active"` in the update request to reactivate an archived supplier and apply the changes.|
+
+#### FreeAgent
+
+| Limitation           | Description                                                                                                                        |
+|----------------------|------------------------------------------------------------------------------------------------------------------------------------|
+| **Supplier name**    | If `supplierName` is `null` in the request, FreeAgent uses the value in `contactName` instead (the value must contain a space). If both fields are `null`, FreeAgent returns a `400` response.         |
+| **Country**          | It's not possible to clear the supplier's country. Sending a `null` value or excluding the field from the request sets the value to the company's default country.                    |
+| **Default currency** | FreeAgent doesn't support currency at supplier level. Any value sent in the request is ignored, and the response returns the company's base currency. |
+
 :::tip Recap
 
 You have learnt how to view, create, and update your customer's suppliers who provide them with goods and services.

docs/using-the-api/querying.md

@@ -916,7 +916,7 @@ Query: `dataConnections.status!=PendingAuth&&dataConnections.status!=Linked&&dat
 
 - The page size value is obligatory for querying.
 - The response will exclude companies that had connections but they were deleted.
-  :::
+:::
 
 <Tabs>
 

sidebars/payables.js

@@ -29,8 +29,8 @@ module.exports = [
     },
   },
   "payables/sync/bills",
-  "payables/sync/pay-bill",
   "payables/sync/update-bill",
+  "payables/sync/pay-bill",
   {
     type: "doc",
     id: "payables/sync/sync-data-types",