CONN-801: extend update bills/suppliers docs to Sage Intacct, NetSuite, Zoho Books #1875
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
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 | ||||
|---|---|---|---|---|---|---|
|
|
@@ -64,37 +64,83 @@ Include all fields in the request, even if their values haven't changed. If you | |||||
|
|
||||||
| :::info Software coverage | ||||||
|
|
||||||
| This action is currently only supported for FreeAgent, Oracle NetSuite, QuickBooks Online, Sage Intacct, Xero, and Zoho Books. | ||||||
|
|
||||||
| ::: | ||||||
|
|
||||||
| ### Software-specific behavior | ||||||
|
|
||||||
| Each accounting software has some limitations when updating suppliers. We've summarized them below. | ||||||
|
|
||||||
| <Tabs groupId="software"> | ||||||
|
|
||||||
| <TabItem value="fa" label="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). Codat rejects a request where both fields are `null` with a `400` response, because FreeAgent requires a name. | | ||||||
|
There was a problem hiding this comment. 📝 [vale] <Google.Parens> reported by reviewdog 🐶 |
||||||
| | **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. | | ||||||
|
There was a problem hiding this comment. 📝 [vale] <Google.Passive> reported by reviewdog 🐶 |
||||||
|
|
||||||
| </TabItem> | ||||||
|
|
||||||
| <TabItem value="netsuite" label="NetSuite"> | ||||||
|
|
||||||
| | Limitation | Description | | ||||||
| | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||||||
| | **Status** | Always include `status` in the request. Omitting it reactivates an archived supplier. | | ||||||
| | **Contact name** | `contactName` is not supported on update. Any value sent in the request is ignored and the response returns `null`. | | ||||||
|
There was a problem hiding this comment. 📝 [vale] <Google.Contractions> reported by reviewdog 🐶
Suggested change
There was a problem hiding this comment. 📝 [vale] <Google.Passive> reported by reviewdog 🐶 |
||||||
| | **Duplicate names** | Supplier names must be unique. Updating a name to match an existing supplier returns a `400` response. | | ||||||
| | **Supplier name** | Omitting `supplierName` clears it. Include the existing name if you don't want to change it. | | ||||||
| | **Default currency** | The currency must be enabled in the NetSuite organization, or the update returns a `400` response. Sending a `null` value leaves the existing currency unchanged. | | ||||||
|
There was a problem hiding this comment. 📝 [vale] <Google.Passive> reported by reviewdog 🐶 |
||||||
| | **Country** | Address `country` must be a 2-character ISO code. | | ||||||
|
|
||||||
| </TabItem> | ||||||
|
|
||||||
| <TabItem value="qbo" label="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. | | ||||||
|
|
||||||
| </TabItem> | ||||||
|
|
||||||
| <TabItem value="intacct" label="Sage Intacct"> | ||||||
|
|
||||||
| | Limitation | Description | | ||||||
| | -------------------- | -------------------------------------------------------------------------------------------------------------------- | | ||||||
| | **Supplier name** | It's not possible to clear the supplier name. Sending a `null` value or excluding the field keeps the existing name. | | ||||||
| | **Default currency** | Sending a `null` value keeps the existing currency, but sending `""` clears the supplier's currency on the platform. | | ||||||
| | **Addresses** | Sage Intacct supports a single address per supplier, and the response returns the first address only. | | ||||||
| | **Contact name** | `contactName` is split on the last space into a first and last name, each limited to 40 characters. | | ||||||
|
There was a problem hiding this comment. 📝 [vale] <Google.Passive> reported by reviewdog 🐶 |
||||||
|
|
||||||
| </TabItem> | ||||||
|
|
||||||
| <TabItem value="xero" label="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. | | ||||||
|
|
||||||
| </TabItem> | ||||||
|
|
||||||
| <TabItem value="zoho" label="Zoho Books"> | ||||||
|
|
||||||
| | Limitation | Description | | ||||||
| | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||||||
| | **Supplier name** | It's not possible to clear the supplier name. Sending a `null` value or excluding the field keeps the existing name. | | ||||||
| | **Duplicate names** | Supplier names must be unique, unless the Zoho Books organization allows duplicate vendor names. Updating a name to match an existing supplier returns a `400` response. | | ||||||
| | **Default currency** | The currency must exist in the Zoho Books organization's currency list, or the update returns a `400` response. Sending a `null` value keeps the existing currency. Changing a supplier's currency also changes the currency of bills created for that supplier, because Zoho Books derives bill currency from the supplier. | | ||||||
| | **Addresses** | Billing and delivery addresses are replaced together. Sending only a billing address clears the delivery address. | | ||||||
|
There was a problem hiding this comment. 📝 [vale] <Google.Passive> reported by reviewdog 🐶 |
||||||
| | **Archived suppliers** | Archived suppliers can still be updated — the field changes are applied and the supplier remains archived. A rejected update never changes the supplier's status. | | ||||||
|
There was a problem hiding this comment. 📝 [vale] <Google.Passive> reported by reviewdog 🐶 There was a problem hiding this comment. 🚫 [vale] <Google.EmDash> reported by reviewdog 🐶
Suggested change
There was a problem hiding this comment. 📝 [vale] <Google.Passive> reported by reviewdog 🐶 |
||||||
|
|
||||||
| </TabItem> | ||||||
|
|
||||||
| </Tabs> | ||||||
|
|
||||||
| :::tip Recap | ||||||
|
|
||||||
|
|
||||||
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 | ||||
|---|---|---|---|---|---|---|
|
|
@@ -16,7 +16,7 @@ We distinguish between invoices where the company _owes_ money and those where t | |||||
|
|
||||||
| :::info Software coverage | ||||||
|
|
||||||
| This action is currently only supported for FreeAgent, Oracle NetSuite, QuickBooks Online, Sage Intacct, Xero, and Zoho Books. | ||||||
|
There was a problem hiding this comment. 📝 [vale] <Google.Timeless> reported by reviewdog 🐶 |
||||||
|
|
||||||
| ::: | ||||||
|
|
||||||
|
|
@@ -101,6 +101,50 @@ PUT /companies/{companyId}/connections/{dataConnectionId}/payables/bills/{billId | |||||
|
|
||||||
| </TabItem> | ||||||
|
|
||||||
| <TabItem value="netsuite" label="NetSuite example"> | ||||||
|
|
||||||
| ```json | ||||||
| { | ||||||
| "description": "Consulting", | ||||||
| "unitAmount": 500, | ||||||
| "quantity": 2, | ||||||
| "accountRef": { "id": "<account-internal-id>" }, | ||||||
| "taxRateRef": { "id": "<tax-code-internal-id>" }, | ||||||
| "trackingRefs": [ | ||||||
| { | ||||||
| "id": "department-<department-internal-id>", | ||||||
| "dataType": "trackingCategories" | ||||||
| }, | ||||||
| { | ||||||
| "id": "location-<location-internal-id>", | ||||||
| "dataType": "trackingCategories" | ||||||
| }, | ||||||
| { | ||||||
| "id": "<customer-internal-id>", | ||||||
| "dataType": "customers", | ||||||
| "isBillable": true | ||||||
| } | ||||||
| ] | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| </TabItem> | ||||||
|
|
||||||
| <TabItem value="intacct" label="Sage Intacct example"> | ||||||
|
|
||||||
| ```json | ||||||
| { | ||||||
| "description": "Consulting", | ||||||
| "unitAmount": 500, | ||||||
| "quantity": 2, | ||||||
| "accountRef": { "id": "<account-record-number>" }, | ||||||
| "taxRateRef": { "id": "<tax-detail-id>" }, | ||||||
| "taxAmount": 200 | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| </TabItem> | ||||||
|
|
||||||
| <TabItem value="xero" label="Xero example"> | ||||||
|
|
||||||
| ```json | ||||||
|
|
@@ -116,19 +160,38 @@ PUT /companies/{companyId}/connections/{dataConnectionId}/payables/bills/{billId | |||||
|
|
||||||
| </TabItem> | ||||||
|
|
||||||
| <TabItem value="zoho" label="Zoho Books example"> | ||||||
|
|
||||||
| ```json | ||||||
| { | ||||||
| "description": "Consulting", | ||||||
| "unitAmount": 500, | ||||||
| "quantity": 2, | ||||||
| "accountRef": { "id": "<account-id>" }, | ||||||
| "taxRateRef": { "id": "<tax-rate-id>" }, | ||||||
| "taxAmount": 200, | ||||||
| "trackingRefs": [ | ||||||
| { "id": "<tag-id>-<tag-option-id>", "dataType": "trackingCategories" }, | ||||||
| { "id": "<customer-id>", "dataType": "customers", "isBillable": true } | ||||||
| ] | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| </TabItem> | ||||||
|
|
||||||
| </Tabs> | ||||||
|
|
||||||
| ### Software requirements | ||||||
|
|
||||||
| We have summarized the key differences between the integrations that support updates to bills below: | ||||||
|
|
||||||
| | Feature | FreeAgent | NetSuite | QBO | Sage Intacct | Xero | Zoho Books | | ||||||
| | ------------------------ | -------------------- | --------------------------------- | ------------------- | --------------------------------- | ------------------- | ------------------------------------ | | ||||||
| | **Reference max length** | 255 characters | 45 characters | 21 characters | 100 characters | 255 characters | 50 characters | | ||||||
| | **`TaxRateRef`** | Must be `null` | Required with `taxAmount` | Required | Required with `taxAmount` | Required | Required with a non-zero `taxAmount` | | ||||||
| | **Tax handling** | Use `taxAmount` only | Use `taxRateRef.id` + `taxAmount` | Use `taxRateRef.id` | Use `taxRateRef.id` + `taxAmount` | Use `taxRateRef.id` | Use `taxRateRef.id` + `taxAmount` | | ||||||
| | **`AccountRef` format** | Nominal code | Internal ID | Numeric string | Account record number | GUID | Numeric ID | | ||||||
| | **Max line items** | 40 | No limit | No limit | No limit | No limit | No limit | | ||||||
|
|
||||||
| ### Validation errors | ||||||
|
|
||||||
|
|
@@ -165,6 +228,26 @@ You may encounter a validation error when sending a request to update a bill. In | |||||
|
|
||||||
| </TabItem> | ||||||
|
|
||||||
| <TabItem value="netsuite" label="NetSuite"> | ||||||
|
|
||||||
| | Issue | Error message | | ||||||
| | ------------------------------- | ----------------------------------------- | | ||||||
| | Invalid supplier ID | `Supplier Ref` was not found in NetSuite. | | ||||||
|
There was a problem hiding this comment. 📝 [vale] <Google.Contractions> reported by reviewdog 🐶
Suggested change
|
||||||
| | Invalid account ID | `Account Ref` was not found in NetSuite. | | ||||||
|
There was a problem hiding this comment. 📝 [vale] <Google.Contractions> reported by reviewdog 🐶
Suggested change
|
||||||
| | Invalid tax rate ID | `Tax Rate Ref` was not found in NetSuite. | | ||||||
|
There was a problem hiding this comment. 📝 [vale] <Google.Contractions> reported by reviewdog 🐶
Suggested change
|
||||||
| | Changed or unsupported currency | `Currency` is not supported for supplier. | | ||||||
|
There was a problem hiding this comment. 📝 [vale] <Google.Contractions> reported by reviewdog 🐶
Suggested change
|
||||||
|
|
||||||
| </TabItem> | ||||||
|
|
||||||
| <TabItem value="intacct" label="Sage Intacct"> | ||||||
|
|
||||||
| | Issue | Error message | | ||||||
| | ------------------------- | ----------------------------------------------------------------------- | | ||||||
| | Bill fully or partly paid | This bill has been paid or partially paid and can no longer be updated. | | ||||||
|
There was a problem hiding this comment. 📝 [vale] <Google.Passive> reported by reviewdog 🐶 There was a problem hiding this comment. 📝 [vale] <Google.Passive> reported by reviewdog 🐶 |
||||||
| | Invalid supplier ID | The Supplier with Id `<id>` was not found. | | ||||||
|
There was a problem hiding this comment. 📝 [vale] <Google.Contractions> reported by reviewdog 🐶
Suggested change
|
||||||
|
|
||||||
| </TabItem> | ||||||
|
|
||||||
| <TabItem value="qbo" label="QuickBooks Online"> | ||||||
|
|
||||||
| | Issue | Error message | | ||||||
|
|
@@ -184,6 +267,17 @@ You may encounter a validation error when sending a request to update a bill. In | |||||
|
|
||||||
| </TabItem> | ||||||
|
|
||||||
| <TabItem value="zoho" label="Zoho Books"> | ||||||
|
|
||||||
| | Issue | Error message | | ||||||
| | -------------------------- | ------------------------------------------------- | | ||||||
| | Duplicate reference | Reference has already been used for this supplier | | ||||||
|
There was a problem hiding this comment. 📝 [vale] <Google.Passive> reported by reviewdog 🐶 |
||||||
| | Invalid supplier ID | `SupplierRef Id` was not found in ZohoBooks. | | ||||||
|
There was a problem hiding this comment. 📝 [vale] <Google.Contractions> reported by reviewdog 🐶
Suggested change
|
||||||
| | Negative bill total | The total amount due cannot be negative. | | ||||||
|
There was a problem hiding this comment. 📝 [vale] <Google.Contractions> reported by reviewdog 🐶
Suggested change
|
||||||
| | Due date before issue date | `dueDate` must be after `issueDate`. | | ||||||
|
|
||||||
| </TabItem> | ||||||
|
|
||||||
| </Tabs> | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
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.
📝 [vale] <Google.Timeless> reported by reviewdog 🐶
Avoid time-based words like 'currently' in product documentation.