Update bills

Update existing bills using Codat's Bill Pay solution

Invoices or bills?

We distinguish between invoices where the companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. owes money and those where the companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. is owed money. If the companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. receives an invoice and owes money as a result, we call this a bill.

Update a bill

Software coverage

This action is currently only supported for FreeAgent, QuickBooks Online, and Xero.

In some cases, your SMBSMB The primary customer segment that Codat helps businesses serve, typically companies with annual revenues under $500 million. 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 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.
• During the update, all existing bill line items will removed and replaced with new line items.
• You can change the following values:
  • reference
  • supplierRef.id
  • issueDate
  • dueDate
  • currency
  • currencyRate
  • lineItems[]

For integration-specific rules and errors, review the Software requirements section.

---

Example payloads

Request structure

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" }]
    }
  ]
}

FreeAgent example

{
  "description": "Consulting",
  "unitAmount": 500,
  "quantity": 2,
  "accountRef": { "id": "<nominal-code>" },
  "taxAmount": 200,
  "trackingRefs": [{ "id": "<project-id>", "isBillable": true }]
}

QBO example

{
  "description": "Consulting",
  "unitAmount": 500,
  "quantity": 2,
  "accountRef": { "id": "<account-id>" },
  "taxRateRef": { "id": "<tax-rate-id>" }
}

Xero example

{
  "description": "Consulting",
  "unitAmount": 500,
  "quantity": 2,
  "accountRef": { "id": "<account-guid>" },
  "taxRateRef": { "id": "<tax-rate-code>" },
  "trackingRefs": [{ "id": "<tracking-option-guid>" }]
}

Software requirements

We have summarized the key differences between the integrations that support updates to bills below:

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

FreeAgent

Issue	Error message
Invalid account code	Account Ref was not found in FreeAgent.
Invalid supplier ID	Supplier Ref Id was not found in FreeAgent.

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.

Xero

Issue	Error message
Invalid account GUID	Account Ref was not found in Xero.
Invalid supplier ID	SupplierRef Id was not found in Xero.
Currency not enabled	No currency exists for code currency.

---

Read next

• Enable your customers to pay single bills to complete the Bill Pay process.