Skip to main content

Manage bills

View and create bills using Codat's async Bill Pay solution

Invoices or bills?

We distinguish between invoices where the company owes money and those where the company is owed money. If the company receives an invoice and owes money as a result, we call this a bill.

Overview​

In Codat, a bill represents an accounts payable invoice issued to an SMB by their supplier. With asynchronous Bill Pay, you can:

  • Retrieve and update your customer's existing bills.
  • Create new bills in your system and reflect them in your customer's accounting software.

We have highlighted this alternative sequence of steps in our detailed process diagram below.

Detailed process diagram

Retrieve bills​

Narrow down the bill list

Bill endpoints of the async Bill Pay solution provide full, unfiltered bill records. You can use query parameters to narrow down the list of results. For example:

  • supplierRef.supplierName=acme returns bills associated with the specified supplier.
  • dueDate>2023-06-01&&dueDate<2023-06-30 returns bills due for payment between 1 and 30 June.
  • amountDue>0 returns outstanding bills with non-zero due amounts.

Call our List bills endpoint to retrieve the full list of a company's existing bills.

You can also Download bill attachments associated with a given bill, such as a PDF copy of the accounts payable invoice issued by the supplier.

const billsResponse = await payablesClient.bills.list({
    companyId: companyId,
    query: 'supplierRef.supplierName=acme'
  });

Create bill​

Reference data

Bills should always correspond to a supplier that issued them. Ensure the relevant supplier exists before creating a new bill.

You may also need to associate the bill's line items with a specific account or tax rate. Use the List accounts or Create account endpoints to manage available reference accounts and List tax rates to view tax rates available to assign.

Use the Create bills endpoint to create a new bill in your SMB customer's accounting software that represents the outstanding payment for goods or services purchased from a supplier.

const billCreateResponse = await payablesClient.bills.create({
    bill: {
      supplierRef: {
        id: supplierCreateResponse.supplier.id,
        supplierName: supplierCreateResponse.supplier.supplierName
      },
      issueDate: "2023-04-23T00:00:00",
      dueDate: "2023-10-23T00:00:00",
      lineItems: [
        {
          "description": "Half day training - Microsoft Paint",
          "unitAmount": 1000.00,
          "quantity": 1,
          "totalAmount": 1000.00,
        }
      ],
      status: BillStatus.Open,
      subTotal: 1000.00,
      taxAmount: 200.00,
      totalAmount: 1200.00,
      amountDue: 1200.00
    },
    companyId: companyId,
    connectionId: connectionId,
  });

Update bill​

In some cases, your SMB 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.

const billUpdateResponse = await payablesClient.bills.update({
    bill: {
      supplierRef: {
        id: supplierCreateResponse.supplier.id,
        supplierName: supplierCreateResponse.supplier.supplierName
      },
      issueDate: "2023-04-23T00:00:00",
      dueDate: "2023-06-23T00:00:00",
      lineItems: [
        {
          "description": "Half day training - Microsoft Paint",
          "unitAmount": 1000.00,
          "quantity": 1,
          "totalAmount": 1000.00,
        }
      ],
      status: BillStatus.Open,
      subTotal: 1000.00,
      taxAmount: 200.00,
      totalAmount: 1200.00,
      amountDue: 1200.00
    },
    companyId: companyId,
    connectionId: connectionId,
    billId: billId,
  });

Delete bill​

In certain scenarios, your SMB customer may want to delete an existing bill or a bill payment - for example, if they made a mistake or no longer want to process the bill.

Use the Delete bill endpoint to support these requirements, and check the OAS for the most up-to-date integration coverage.

const billDeleteResponse = await payablesClient.bills.delete({
  companyId: companyId,
  connectionId: connectionId,
  billId: billId,
});

Upload attachment​

When creating a new bill, your SMB customer may want to save a copy of the PDF invoice issued by their supplier against the bill in their accounting software. Use the Upload bill attachment endpoint to support this action.

Different accounting software supports different file formats and sizes. View the Attachment schema for integration-specific guidance or check the software's own documentation.

const fileName = 'bill-receipt.pdf';
var fs = require('fs');
var fileBuffer = fs.readFileSync(fileName, null).buffer;
var fileArray = new Uint16Array( fileBuffer.slice(266,(sizeofArray*sizeOfArrayElement));

const attachmentUploadResponse = await payablesClient.bills.uploadAttachment({
    attachmentUpload: {
      file: {
        content: fileArray,
        fileName: fileName,
      },
    },
    billId: billId,
    companyId: companyId,
    connectionId: connectionId,
  });
  • Enable your customers to make payments covering their outstanding bills.
Was this page useful?
👏
👍
🤔
👎
😭

Contents

Suggest edits