Bills (beta)

A Bill is used to record a business transaction where the items and services from a Vendor have been provided to the business owner, but payment isn’t due until a later date. If you’ve already paid for an item or service in full, this would be an Expense instead. A bill is associated with a Vendor, so make sure to create/retrieve your vendor before you create a bill. See Bill Payments for paying a bill.

Access Requirements

Access	Requires Authorization
Scopes	`user:bills:read user:bills:write`

Includes

Include Name	Description
vendor	include vendor details in response

Searches / Filters

Name	Field	Filter Type	Description
vendorid	vendorid	Equals	matches the id of the vendor
statuses	status	In	matches list of bill statuses
currency_code	currency_code	Equals	Eg. “USD”
ids	id	In	matches list of bill ids

Field Descriptions

underlined fields are required on creation

Field New Descriptions

Field	Type	Description
amount	object	Read-only. Computed from lines. subfields: amount and code
– amount	string	bill subtotatal amount excluding the taxes
– code	string	three-letter currency code
attachment	object
bill_number	string	reference to vendor bill number
bill_payments	array	Bill Payments made against the bill
created_at	datetime	Read-only. time the invoice was created, YYYY-MM-DD HH:MM:SS format
currency_code	string	three-letter currency code
due_date	date	date for which the bill is due for payment
due_offset_days	integer	number of days from the issue date that the invoice needs to be set to due
id	integer	uniquely identifies the bill associated with the business.
issue_date	date	date when the bill was issued by the vendor
language	string	two-letter language code, e.g. “en”
lines	array	array of bill line items, refer to bill line items object below
outstanding	object	Read-only. subfields: amount and code
– amount	string	outstanding/unpaid amount on the bill
– code	string	three-letter currency code
overall_category	string	Read-only. If multiple categories are selected in the bill lines, then overall_category is Split. Otherwise, it will be the selected category.
overall_description	string	Read-only. First non-null value of bill line descriptions
paid	object	Read-only. subfields: amount and code
– amount	string	Paid amount on the bill
– code	string	three-letter currency code
status	string	Read-only. Status of the bill: “unpaid”, “overdue”, “partial”, “paid”
tax_amount	object	Read-only. Computed from lines. subfields: amount and code
– amount	string	total tax amount on the bill
– code	string	three-letter currency code
total_amount	object	Read-only. Computed from lines. subfields: amount and code
– amount	string	grand total amount on bill amount tax amount
– code	string	three-letter currency code
updated_at	string	Read-only. last time the resource was updated. YYYY-MM-DD HH:MM:SS format
vendorid	integer
vis_state	integer	0 for active, 1 for deleted, 2 for archived

Lines

Bill lines are used to determine the amount of a bill. Note:When updating lines with a PUT request, the request payload must contain all the lines of the invoice that you wish to remain.

Field	Type	Description
categoryid	integer	id of related expense category
category	string	Read-only. Name of related expense category
list_index	integer	Read-only. Line number on the Bill
description	string	description for the line item
quantity	integer	quantity of the line unit
unit_cost	object	unit cost of the line item. subfields: amount and code
– amount	string	unit cost amount, to two decimal places
– code	string	three-letter currency code
amount	object	Read-only. Total amount calculated from quantity and unit_cote
– amount	string	amount
– code	string	three-letter currency code
total_amount	object	Read-only.
– amount	string
– code	string	three-letter currency code
tax_name1	string	name for the first tax on the bill line
tax_name2	string	name for the second tax on the bill line
tax_percent1	integer	Percentage of first tax to 2 decimal places
tax_percent2	integer	Percentage of second tax to 2 decimal places
tax_authorityid1	string
tax_authorityid2	string
tax_amount1	object	Read-only. Calculated from tax details. subfields: amount and code
– amount	string	Paid amount on the bill
– code	string	three-letter currency code
tax_amount2	object	Read-only. Calculated from tax details. subfields: amount and code
– amount	string	total tax amount on the bill
– code	string	three-letter currency code

Get Single Bill

curl -L -X GET 'https://api.freshbooks.com/accounting/account/<accountId>/bills/bills/<billId>' \
-H 'Authorization: Bearer <insert-bearer-token>'

#Response:
{
  "response":{
    "result":{
      "bill":{
        "amount":{
          "amount":"1500.00",
          "code":"EUR"
        },
        "attachment":null,
        "bill_number":"BN101",
        "bill_payments":[
          
        ],
        "created_at":"2021-01-28 15:06:32",
        "currency_code":"EUR",
        "due_date":"2021-02-27",
        "due_offset_days":30,
        "id":1141,
        "issue_date":"2021-01-28",
        "language":"en",
        "lines":[
          {
            "amount":{
              "amount":"1500.00",
              "code":"EUR"
            },
            "category":{
              "category":"Equipment",
              "categoryid":3696445,
              "created_at":"2020-12-01 08:16:47",
              "id":3696445,
              "is_cogs":false,
              "is_editable":false,
              "parentid":3696439,
              "updated_at":"2020-12-01 08:16:47",
              "vis_state":0
            },
            "description":"Raw material",
            "id":2621,
            "list_index":1,
            "quantity":"15",
            "tax_amount1":null,
            "tax_amount2":null,
            "tax_authorityid1":null,
            "tax_authorityid2":null,
            "tax_name1":null,
            "tax_name2":null,
            "tax_percent1":null,
            "tax_percent2":null,
            "total_amount":{
              "amount":"1500.00",
              "code":"EUR"
            },
            "unit_cost":{
              "amount":"100.00",
              "code":"EUR"
            }
          }
        ],
        "outstanding":{
          "amount":"1500.00",
          "code":"EUR"
        },
        "overall_category":"Equipment",
        "overall_description":"Raw material",
        "paid":{
          "amount":"0.00",
          "code":"EUR"
        },
        "status":"unpaid",
        "tax_amount":{
          "amount":"0.00",
          "code":"EUR"
        },
        "total_amount":{
          "amount":"1500.00",
          "code":"EUR"
        },
        "updated_at":"2021-01-28 15:06:53",
        "vis_state":0
      }
    }
  }
}

Get Bills

curl -L -X GET 'https://api.freshbooks.com/accounting/account/<accountId>/bills/bills/' \
-H 'Authorization: Bearer <insert-bearer-token>'

#Response:

 {
  "response":{
    "result":{
      "bills":[
        {
          "amount":{
            "amount":"1500.00",
            "code":"EUR"
          },
          "attachment":null,
          "bill_number":"BN101",
          "bill_payments":[
            
          ],
          "created_at":"2021-01-28 15:06:32",
          "currency_code":"EUR",
          "due_date":"2021-02-27",
          "due_offset_days":30,
          "id":1141,
          "issue_date":"2021-01-28",
          "language":"en",
          "lines":[
            {
              "amount":{
                "amount":"1500.00",
                "code":"EUR"
              },
              "category":{
                "category":"Equipment",
                "categoryid":3696445,
                "created_at":"2020-12-01 08:16:47",
                "id":3696445,
                "is_cogs":false,
                "is_editable":false,
                "parentid":3696439,
                "updated_at":"2020-12-01 08:16:47",
                "vis_state":0
              },
              "description":"Raw material",
              "id":2621,
              "list_index":1,
              "quantity":"15",
              "tax_amount1":null,
              "tax_amount2":null,
              "tax_authorityid1":null,
              "tax_authorityid2":null,
              "tax_name1":null,
              "tax_name2":null,
              "tax_percent1":null,
              "tax_percent2":null,
              "total_amount":{
                "amount":"1500.00",
                "code":"EUR"
              },
              "unit_cost":{
                "amount":"100.00",
                "code":"EUR"
              }
            }
          ],
          "outstanding":{
            "amount":"1500.00",
            "code":"EUR"
          },
          "overall_category":"Equipment",
          "overall_description":"Raw material",
          "paid":{
            "amount":"0.00",
            "code":"EUR"
          },
          "status":"unpaid",
          "tax_amount":{
            "amount":"0.00",
            "code":"EUR"
          },
          "total_amount":{
            "amount":"1500.00",
            "code":"EUR"
          },
          "updated_at":"2021-01-28 15:06:53",
          "vis_state":0
        }
      ],
      "page":1,
      "pages":4,
      "per_page":1,
      "total":4
    }
  }
}

Create a Bill

curl -L -X POST 'https://api.freshbooks.com/accounting/account/<accountId>/bills/bills' \
-H 'Authorization: Bearer <insert-bearer-token>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "bill": {
        "vendorid": "1562",
        "bill_number": null,
        "issue_date": "2021-06-16",
        "due_offset_days": 30,
        "currency_code": "USD",
        "language": "en",
        "lines": [
            {
                "tax_percent1": 6,
                "tax_percent2": null,
                "unit_cost": {
                    "amount": "600",
                    "code": "USD"
                },
                "description": "Volkoren Brood",
                "tax_name1": "GST1",
                "quantity": 40,
                "tax_name2": null,
                "compounded_tax": false,
                "categoryid": "3696397"
            }
        ],
        "attachment": null
    }
}'

#Response:
 {
  "response":{
    "result":{
      "bill":{
        "amount":{
          "amount":"375.00",
          "code":"USD"
        },
        "attachment":null,
        "bill_number":null,
        "bill_payments":[
          
        ],
        "created_at":"2020-10-09 15:28:49",
        "currency_code":"USD",
        "due_date":"2020-11-17",
        "due_offset_days":39,
        "id":7,
        "issue_date":"2020-10-09",
        "language":"en",
        "lines":[
          {
            "amount":{
              "amount":"125.00",
              "code":"USD"
            },
            "category":{
              "category":"Office Expenses & Postage",
              "categoryid":65773,
              "created_at":"2016-11-17 14:22:35",
              "id":65773,
              "is_cogs":false,
              "is_editable":false,
              "parentid":null,
              "updated_at":"2016-11-17 14:22:35",
              "vis_state":0
            },
            "description":"Malm Side Table",
            "id":13,
            "list_index":1,
            "quantity":"1",
            "tax_amount1":null,
            "tax_amount2":null,
            "tax_authorityid1":null,
            "tax_authorityid2":null,
            "tax_name1":null,
            "tax_name2":null,
            "tax_percent1":null,
            "tax_percent2":null,
            "total_amount":{
              "amount":"125.00",
              "code":"USD"
            },
            "unit_cost":{
              "amount":"125.00",
              "code":"USD"
            }
          },
          {
            "amount":{
              "amount":"250.00",
              "code":"USD"
            },
            "category":{
              "category":"Office Expenses & Postage",
              "categoryid":65773,
              "created_at":"2016-11-17 14:22:35",
              "id":65773,
              "is_cogs":false,
              "is_editable":false,
              "parentid":null,
              "updated_at":"2016-11-17 14:22:35",
              "vis_state":0
            },
            "description":"Malm Book Shelf",
            "id":15,
            "list_index":2,
            "quantity":"1",
            "tax_amount1":null,
            "tax_amount2":null,
            "tax_authorityid1":null,
            "tax_authorityid2":null,
            "tax_name1":null,
            "tax_name2":null,
            "tax_percent1":null,
            "tax_percent2":null,
            "total_amount":{
              "amount":"250.00",
              "code":"USD"
            },
            "unit_cost":{
              "amount":"250.00",
              "code":"USD"
            }
          }
        ],
        "outstanding":{
          "amount":"375.00",
          "code":"USD"
        },
        "overall_category":"Office Expenses & Postage",
        "overall_description":"Malm Side Table",
        "paid":{
          "amount":"0.00",
          "code":"USD"
        },
        "status":"unpaid",
        "tax_amount":{
          "amount":"0.00",
          "code":"USD"
        },
        "total_amount":{
          "amount":"375.00",
          "code":"USD"
        },
        "updated_at":"2020-10-09 15:28:49",
        "vis_state":0
      }
    }
  }
}

Delete Bill

curl -L -X PUT 'https://api.freshbooks.com/accounting/account/<accountId>/bills/bills/<billId>' \
-H 'Authorization: Bearer <insert-bearer-token>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "bill": {
        "vis_state": 1
    }
}'

#Response:
 {
    "response": {
        "result": {
            "bill": {
                "amount": {
                    "amount": "1500.00",
                    "code": "EUR"
                },
                "attachment": null,
                "bill_number": "BN101",
                "bill_payments": [],
                "created_at": "2021-01-28 15:06:32",
                "currency_code": "EUR",
                "due_date": "2021-02-27",
                "due_offset_days": 30,
                "id": 1141,
                "issue_date": "2021-01-28",
                "language": "en",
                "lines": [
                    {
                        "amount": {
                            "amount": "1500.00",
                            "code": "EUR"
                        },
                        "category": {
                            "category": "Equipment",
                            "categoryid": 3696445,
                            "created_at": "2020-12-01 08:16:47",
                            "id": 3696445,
                            "is_cogs": false,
                            "is_editable": false,
                            "parentid": 3696439,
                            "updated_at": "2020-12-01 08:16:47",
                            "vis_state": 0
                        },
                        "description": "Raw material",
                        "id": 2621,
                        "list_index": 1,
                        "quantity": "15",
                        "tax_amount1": null,
                        "tax_amount2": null,
                        "tax_authorityid1": null,
                        "tax_authorityid2": null,
                        "tax_name1": null,
                        "tax_name2": null,
                        "tax_percent1": null,
                        "tax_percent2": null,
                        "total_amount": {
                            "amount": "1500.00",
                            "code": "EUR"
                        },
                        "unit_cost": {
                            "amount": "100.00",
                            "code": "EUR"
                        }
                    }
                ],
                "outstanding": {
                    "amount": "1500.00",
                    "code": "EUR"
                },
                "overall_category": "Equipment",
                "overall_description": "Raw material",
                "paid": {
                    "amount": "0.00",
                    "code": "EUR"
                },
                "status": "overdue",
                "tax_amount": {
                    "amount": "0.00",
                    "code": "EUR"
                },
                "total_amount": {
                    "amount": "1500.00",
                    "code": "EUR"
                },
                "updated_at": "2021-06-16 10:33:38",
                "vis_state": 1
            }
        }
    }
}

Archive Bill

curl -L -X PUT 'https://api.freshbooks.com/accounting/account/<accountId>/bills/bills/<billId>' \
-H 'Authorization: Bearer <insert-bearer-token>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "bill": {
        "vis_state": 2
    }
}'

#Response:
 {
    "response": {
        "result": {
            "bill": {
                "amount": {
                    "amount": "1500.00",
                    "code": "EUR"
                },
                "attachment": null,
                "bill_number": "BN101",
                "bill_payments": [],
                "created_at": "2021-01-28 15:06:32",
                "currency_code": "EUR",
                "due_date": "2021-02-27",
                "due_offset_days": 30,
                "id": 1141,
                "issue_date": "2021-01-28",
                "language": "en",
                "lines": [
                    {
                        "amount": {
                            "amount": "1500.00",
                            "code": "EUR"
                        },
                        "category": {
                            "category": "Equipment",
                            "categoryid": 3696445,
                            "created_at": "2020-12-01 08:16:47",
                            "id": 3696445,
                            "is_cogs": false,
                            "is_editable": false,
                            "parentid": 3696439,
                            "updated_at": "2020-12-01 08:16:47",
                            "vis_state": 0
                        },
                        "description": "Raw material",
                        "id": 2621,
                        "list_index": 1,
                        "quantity": "15",
                        "tax_amount1": null,
                        "tax_amount2": null,
                        "tax_authorityid1": null,
                        "tax_authorityid2": null,
                        "tax_name1": null,
                        "tax_name2": null,
                        "tax_percent1": null,
                        "tax_percent2": null,
                        "total_amount": {
                            "amount": "1500.00",
                            "code": "EUR"
                        },
                        "unit_cost": {
                            "amount": "100.00",
                            "code": "EUR"
                        }
                    }
                ],
                "outstanding": {
                    "amount": "1500.00",
                    "code": "EUR"
                },
                "overall_category": "Equipment",
                "overall_description": "Raw material",
                "paid": {
                    "amount": "0.00",
                    "code": "EUR"
                },
                "status": "overdue",
                "tax_amount": {
                    "amount": "0.00",
                    "code": "EUR"
                },
                "total_amount": {
                    "amount": "1500.00",
                    "code": "EUR"
                },
                "updated_at": "2021-06-16 10:33:38",
                "vis_state": 1
            }
        }
    }
}

Bills (beta)

Access Requirements

Includes

Searches / Filters

Field Descriptions

Lines

Get Single Bill

Get Bills

Create a Bill

Delete Bill

Archive Bill

Get Bills

Add Bill from Vendor

Delete Bill

Archive Bill