This is a staging build of the docs. Do not share the link externally.
Skip to main content

Manage bills

View and create bills using Sync for Payables

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

The fallback content to display on prerendering
represents an accounts payable invoice issued to an SMB by their
The fallback content to display on prerendering
. With Sync for Payables, 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​

Call our List bills endpoint to retrieve the full list of a company's existing bills. 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.

You can also retrieve 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'
  });

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,
  });

Create bill​

Corresponding supplier

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

Use the Create bill 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,
  });

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 platform'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,
  });
Was this page useful?
❤️
👍
🤔
👎
😭

Contents

Suggest edits