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 |
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 } } } }
Get Bills
Request: GET https://api.freshbooks.com/accounting/account/<accountid>/bills/bills
url = "https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses/<id>"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = requests.get(url, data=None, headers=headers)
jsonData = res.json()
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
}
}
}Add Bill from Vendor
Request: POST
https://api.freshbooks.com/accounting/account/<accountid>/bills/bills
url = "https://api.freshbooks.com/accounting/account/<accountid>/bills/bills"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {
"bill":{
"vendorid":"5",
"previous_vendor_id":null,
"bill_number":null,
"issue_date":"2020-10-09",
"due_offset_days":39,
"currency_code":"USD",
"language":"en",
"lines":[
{
"tax_percent1":null,
"tax_percent2":null,
"unit_cost":{
"amount":"125",
"code":"USD"
},
"description":"Malm Side Table",
"tax_name1":null,
"quantity":1,
"tax_name2":null,
"compounded_tax":false,
"categoryid":"65773"
},
{
"tax_percent1":null,
"tax_percent2":null,
"unit_cost":{
"amount":"250",
"code":"USD"
},
"description":"Malm Book Shelf",
"tax_name1":null,
"quantity":1,
"tax_name2":null,
"compounded_tax":false,
"categoryid":"65773"
}
],
"attachment":null
}
}
res = requests.post(url, data=json.dumps(payload), headers=headers)
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
Request: PUT
https://api.freshbooks.com/accounting/account/<accountid>/bills/bills/<billid>
url = "https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses/<id>"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {
"bill":{
"vis_state":1
}
}
res = requests.put(url, data=json.dumps(payload), headers=headers)
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-02-02 19:09:08",
"vis_state":1
}
}
}
}Archive Bill
Request: PUT
https://api.freshbooks.com/accounting/account/<accountid>/bills/bills/<billid>
url = "https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses/<id>"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {
"bill":{
"vis_state":2
}
}
res = requests.put(url, data=json.dumps(payload), headers=headers)
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-02-02 19:09:08",
"vis_state":2
}
}
}
}