Manage suppliers

View, create, and update suppliers using Bill Pay

Overview

In accounts payable, each bill is associated with a supplier. The supplier represents a business or a sole trader that provides goods or services to your SMBSMB The primary customer segment that Codat helps businesses serve, typically companies with annual revenues under $500 million. customer.

Their records also contain key information, such as contact details, that can be used to notify the supplier once a payment is made.

To pay a bill in Bill Pay, you can use your customer's existing suppliers or create a new one. We have highlighted this alternative sequence of steps in our detailed process diagram below.

Detailed process diagram

Narrow down the supplier list

Supplier endpoints of the Bill Pay solution return only active suppliers from the accounting platform. You can use query parameters to narrow down the list of results further.

Retrieve supplier

Call our List suppliers endpoint to retrieve the full list of your customer's existing suppliers.

TypeScript

const suppliersResponse = await payablesClient.suppliers.list({
  companyId: companyId,
});

if (suppliersResponse.statusCode != 200) {
  throw new Error("Could not get current suppliers");
}

console.log(suppliersResponse.suppliers[0].supplierName);

Python

suppliers_request = operations.ListSuppliersRequest(
    company_id=company_id
)

suppliers_response = payables_client.suppliers.list(suppliers_request)

if suppliers_response.status_code != 200:
  raise Exception('Could not get current suppliers')

print(suppliers_response.suppliers[0].supplier_name)

C#

var suppliersResponse = await payablesClient.Suppliers.ListAsync(new() {
    CompanyId = companyId
});

if(suppliersResponse.StatusCode != 200){
  throw new Exception("Could not get current suppliers");
}

Console.WriteLine(suppliersResponse.Suppliers[0].SupplierName);

Go

ctx := context.Background()
suppliersResponse, err := payablesClient.Suppliers.List(ctx,
  operations.ListSuppliersRequest{
    CompanyID: companyID
})

if suppliersResponse.StatusCode == 200 {
  fmt.Println(suppliersResponse.Suppliers[0].SupplierName)
}

Supplier balances

Bill Pay does not expose supplier balances on the supplier endpoints. Instead, you can aggregate bills by supplier.

Create supplier

When your customer's companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. does business with a new supplier for the first time, you will need to create a supplier before creating a bill against that supplier. Use the Create supplier endpoint to do that.

TypeScript

const supplierCreateResponse = await payablesClient.suppliers.create({
  supplier: {
    supplierName: "Kelly's Industrial Supplies",
    contactName: "Kelly's Industrial Supplies",
    emailAddress: "[email protected]",
    status: SupplierStatus.Active,
  },
  companyId: companyId,
  connectionId: connectionId,
});

Python

supplier_create_request = operations.CreateSupplierRequest(
    supplier=shared.Supplier(
        supplier_name="Kelly's Industrial Supplies",
        contact_name="Kelly's Industrial Supplies",
        status=shared.SupplierStatus.ACTIVE,
    ),
    company_id=company_id,
    connection_id=connection_id,
)

supplier_create_response = payables_client.suppliers.create(req)

C#

var supplierCreateResponse = await payablesClient.Suppliers.CreateAsync(new() {
    Supplier = new Supplier() {
        SupplierName = "Kelly's Industrial Supplies",
        ContactName = "Kelly's Industrial Supplies",
        Status = SupplierStatus.Active,
    },
    CompanyId = companyId,
    ConnectionId = connectionId,
});

Go

ctx := context.Background()
supplierCreateResponse, err := payablesClient.Suppliers.Create(ctx, operations.CreateSupplierRequest{
    Supplier: &shared.Supplier{
        SupplierName: syncforpayables.String("Kelly's Industrial Supplies"),
        ContactName: syncforpayables.String("Kelly's Industrial Supplies"),
        Status: shared.SupplierStatusActive,
    },
    CompanyID: companyID,
    ConnectionID: connectionID,
})

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 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.

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.

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.
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 companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources.'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 companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources.'s base currency.

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.
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.
Country	Address country must be a 2-character ISO code.

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.

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.

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 APIAPI A set of rules and protocols that allows different software applications to communicate with each other. Codat provides APIs for accessing financial data from accounting, banking, and commerce platforms.. To unarchive, do it manually in Xero.

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.
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.

Recap

You have learnt how to view, create, and update your customer's suppliers who provide them with goods and services.

Next, you can choose to manage your supplier's bills or payment methods prior to paying those bills.

---

Read next

• Manage your customer's bills
• Pay your customer's bills