Bill Pay Automation

Setting up a Bill Pay Automation (Accounts Payable) workflow with Rutter

Introduction

Rutter's API enables you to handle all of the common workflows needed to offer an Accounts Payable (AP) product to your customers.

Connect to a business entity’s accounting system using Rutter Link.
Create or link the business entity’s Accounts used for logging Bills and Bill Payments.
Create Bills and link Vendors, expense Accounts, Customers, Items, and Tracking Categories (Classes, Locations, and Departments).
Upload Attachments to your logged Bills.
Create and link Bill Payments and Bill Credit Memos to Vendors and unpaid Bills.

See the platform coverage and API endpoint support available for Bill Pay automation.

Connect to the Business Entity's Accounting System

Embed Rutter Link into your application and walk through an end-to-end business authentication flow in order to create a new Connection. This Connection represents the business accounting system and contains an access_token used to read and write data for that instance.

Make your first connection in minutes

Follow our guide to get up and running

Explore Quickstart

Bill Pay Automation (Accounts Payable) Workflow

Setting up Expenses and Accounts Payable Accounts

When recording a bill, every bill debits the expense account and credits the accounts payable account. When recording a bill payment, every bill payment debits the accounts payable account linked to the bill and credits the business entity’s bank or credit card account.

Accounts Payable Account: This is an Account of category = 'liability' and account_type = 'accounts_payable'.
Expense Account: Every bill contains multiple line items, each of which debit an Account of account_type = 'expense'.

Companies vary in their accounting ledger design—some companies may contain an existing account in their chart of accounts for you to link bills and bill payments to, and other companies may require you to create a new account in their chart of accounts.

To retrieve existing accounts, use GET /accounts.
To create new accounts, use POST /accounts.

You can link existing accounts or create new ones if necessary using the above API endpoints to ensure expenses and liabilities are accurately tracked.

Example POST Account API Request Body

1{
2    "account": {      
3      "account_type": "expense",
4      "currency_code": "USD",
5      "name": "Utilities Expense",
6      "nominal_code": "1001",
7      // ...
8    }
9  }

The GET /accounts endpoint lets you fetch all accounts, and you can fetch all expense accounts by adding the filter= account_type ="expense" query filter.

Example GET Account API Response Body

1{
2  "accounts": [
3    {
4      "id": "00000000-0000-0000-0000-000000000000",
5      "platform_id": "12345678",
6      "parent_id": "00000000-0000-0000-0000-000000000000",
7      "account_type": "expense",
8      "category": "expense",
9      "status": "active",
10      "balance": 1250.45,
11      "currency_code": "USD",
12      "name": "Utility Expense",
13      "nominal_code": "1001",
14      //...
15      ],
16      "created_at": "2023-01-02T02:34:56.000Z",
17      "updated_at": "2023-01-02T02:34:56.000Z",
18      "last_synced_at": "2023-01-02T02:34:56.000Z",
19      // ...
20    }
21  ],
22  // ...
23}

Pulling bills from the accounting platform

The GET /bills endpoint lets you ingest any historical bills from an accounting platform and sync them into your app. To receive the latest updates, we recommend polling the GET /bills endpoint and using the Bill webhooks from Rutter. Rutter syncs the latest data for a connection at scheduled intervals.

The Rutter Bill Object also references multiple other objects (such as Accounts, Vendors, Items), so you may also need to fetch all of these related objects to show a Bill in your application.

Example GET Bills API Response Body

1{
2    "bills": [
3      {
4        "id": "00000000-0000-0000-0000-000000000000",
5        "platform_id": "12345678",
6        "account_id": "00000000-0000-0000-0000-000000000000",
7        "payment_terms_id": "00000000-0000-0000-0000-000000000000",
8        "subsidiary_id": "00000000-0000-0000-0000-000000000000",
9        "vendor_id": "00000000-0000-0000-0000-000000000000",
10        "due_date": "2023-01-02T02:34:56.000Z",
11        "issue_date": "2023-01-02T02:34:56.000Z",
12        "amount_due": 9.34,
13        "currency_code": "USD",
14        "status": "partially_paid",
15        "total_amount": 14.34,
16        "document_number": "VENDBILL-1",
17        "memo": "Bill description",
18        "sub_total": 12.34,
19        "tax_amount": 2,
20        "total_discount": 0,
21        "currency_rate": "3.5",
22        "linked_purchase_orders": [
23          {
24            "id": "00000000-0000-0000-0000-000000000000"
25          }
26        ],
27        "linked_credit_memos": [
28          {
29            "id": "00000000-0000-0000-0000-000000000000",
30            "allocated_date": "2023-01-02T02:34:56.000Z",
31            "allocated_amount": 2
32          }
33        ],
34        "linked_payments": [
35          {
36            "id": "00000000-0000-0000-0000-000000000000",
37            "allocated_date": "2023-01-02T02:34:56.000Z",
38            "allocated_amount": 3
39          }
40        ],
41        "line_items": [
42          {
43            "account_id": "00000000-0000-0000-0000-000000000000",
44            "class_id": "00000000-0000-0000-0000-000000000000",
45            "customer_id": "00000000-0000-0000-0000-000000000000",
46            "department_id": "00000000-0000-0000-0000-000000000000",
47            "location_id": "00000000-0000-0000-0000-000000000000",
48            "project_id": "00000000-0000-0000-0000-000000000000",
49            "tax_rate_id": "00000000-0000-0000-0000-000000000000",
50            "description": "A Rutter shirt.",
51            "discount_amount": 0,
52            "discount_percentage": 0,
53            "sub_total": 12.34,
54            "tax_amount": 2,
55            "total_amount": 14.34,
56            "item": {
57              "id": "00000000-0000-0000-0000-000000000000",
58              "quantity": 1,
59              "unit_amount": 12.34
60            }
61          }
62        ],
63        //....
64      }
65    ],
66    //...
67  }

Creating bills from your own application

The POST /bills endpoint lets you create bills from your application and sync them to your user's accounting system. There are a couple of important components:

Vendor: This is the vendor linked to the bill. The GET /vendors and POST /vendors endpoints let you create and link vendors as you log bills.
Item: You may want to tie a bill to an Item in order to better understand cost of goods sold. GET /items lets you fetch all items in the business entity’s catalog.
Expense Account: Every bill contains multiple line items, each of which debit an Account of account_type = 'expense'.
Customer: You may want to tie a bill to a Customer in order to better understand cost of goods sold. GET /customers lets you fetch all customers.
Tracking Categories: Tracking Categories are a way for a businesses to categorize bills. The three main dimensions used for categorization are Locations, Classes, and Departments. Use GET /locations, GET /classes, and GET /departments to fetch and attach the relevant categorizations.

Example POST Bills API Response Body

1{
2    "bill": {
3      "subsidiary_id": "00000000-0000-0000-0000-000000000000",
4      "vendor_id": "00000000-0000-0000-0000-000000000000",
5      "due_date": "2023-01-02T02:34:56.000Z",
6      "issue_date": "2023-01-02T02:34:56.000Z",
7      "currency_code": "USD",
8      "currency_rate": "3.5",
9      "line_items": [
10        {
11          "account_id": "00000000-0000-0000-0000-000000000000",
12          "customer_id": "00000000-0000-0000-0000-000000000000",
13          "tax_rate_id": "00000000-0000-0000-0000-000000000000",
14          "total_amount": 12.34,
15          "description": "A Rutter shirt.",
16          "item": {
17            "id": "00000000-0000-0000-0000-000000000000",
18            "quantity": 1,
19            "unit_amount": 12.34
20          },
21          "class_id": "00000000-0000-0000-0000-000000000000",
22          "department_id": "00000000-0000-0000-0000-000000000000",
23          "location_id": "00000000-0000-0000-0000-000000000000"
24        }
25      ]
26    }
27}

Uploading an attachment to a bill

Typically a bill record has a PDF representation that is helpful to also save to the accounting software. The POST /bills/:id/attachments endpoint lets you upload the bill in PDF or image format and attach it to bills.

Example POST Bill Attachments API Request Body

1{
2    "file": "multipart/form-data",
3    "file_name": "T-shirt Receipt"
4}

Example GET Bill Attachments API Response Body

1{
2    "attachment": {
3      "id": "00000000-0000-0000-0000-000000000000",
4      "platform_id": "12345678",
5      "attached_to_id": "00000000-0000-0000-0000-000000000000",
6      "file_name": "receipt.jpg",
7      "file_url": "https://rutteraccountingattachments.s3.amazonaws.com/00000000-0000-0000-0000-000000000000-receipt.jpg",
8      "attached_to_type": "EXPENSE",
9      "created_at": "2023-01-02T02:34:56.000Z"
10    }
11}

Reconciling bill payments

Typically, applications will show bills and facilitate payments for them. The payments must then be synced into the user's accounting software to ensure their financial records are up-to-date.

To create payment records for Bills in the accounting software, use the POST /bill_payments endpoint.

When logging bill payments, every bill payment credits an account that serves as the source of funds for the payment. This is usually an Account that reflects a credit card (category = 'liability' and account_type = 'credit_card') or a bank (category = 'asset' and account_type = 'bank').

Example POST Bill Payments API Request Body

1{
2    "bill_payment": {
3      "account_id": "00000000-0000-0000-0000-000000000000",
4      "vendor_id": "00000000-0000-0000-0000-000000000000",
5      "transaction_date": "2023-01-02T02:34:56.000Z",
6      "currency_code": "USD",
7      "currency_rate": 1,
8      "memo": "Payment for a shirt.",
9      "linked_bills": [
10        {
11          "id": "00000000-0000-0000-0000-000000000000",
12          "allocated_amount": 12.34
13        }
14      ]
15    }
16}

Creating and applying bill credit memos

There are situations when a vendor provides credit that can be used for paying future bills.

To create and link bill credit memos, you can use POST /bill_credit_memos and POST /bill_credit_applications endpoint. A Bill Credit Memo can be created with POST /bill_credit_memos and is attached to a Vendor. After the bill credit memo is created, it can be later applied to a Bill. You can apply the full amount or a partial amount of the bill credit memo.

Example POST Bill Credit Memos API Request Body

1{
2    "bill_credit_memo": {
3      "account_id": "00000000-0000-0000-0000-000000000000",
4      "vendor_id": "00000000-0000-0000-0000-000000000000",
5      "issue_date": "2023-01-02T02:34:56.000Z",
6      "currency_code": "USD",
7      "line_items": [
8        {
9          "account_id": "00000000-0000-0000-0000-000000000000",
10          "total_amount": 12.34,
11          "description": "A Rutter shirt."
12        }
13      ]
14    }
15}

Example POST Bill Credit Application API Request Body

1{
2    "bill_credit_application": {
3      "bill_credit_memo_id": "00000000-0000-0000-0000-000000000000",
4      "vendor_id": "00000000-0000-0000-0000-000000000000",
5      "transaction_date": "2023-01-02T02:34:56.000Z",
6      "currency_code": "USD",
7      "memo": "Applying vendor credit for bill.",
8      "linked_bills": [
9        {
10          "id": "00000000-0000-0000-0000-000000000000",
11          "allocated_amount": "12.34"
12        }
13      ]
14    }
15}