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

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

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