Log In Items
Items are stored from invoice lines to make invoicing easier in the future.
Access Requirements
| Access | Requires Authorization |
| Scopes | user:billable_items:read |
Includes
There are no includes to specify for items.
Filters
| Filter Type | Name | Field | Description |
|---|---|---|---|
| Equals | itemid | itemid | matches exact itemid |
| Equals | sku | sku | matches exact SKU |
| In | itemids | itemid | matches list of itemids, one specified per query arg |
| Like | description | description | descriptions containing the parameter |
| Between | unit_cost_min | unit_cost | unit costs greater than parameter |
| Between | unit_cost_max | unit_cost | unit costs less than parameter |
| Between | inventory_min | inventory | inventory count greater than parameter |
| Between | inventory _max | inventory | inventory count less than parameter |
| Between | updated_min | updated | date greater than or equal to parameter, YYYY-MM-DD format |
| Between | updated_max | updated | date less than parameter, YYYY-MM-DD format |
| Between | qty_min | qty | quantity greater than parameter |
| Between | qty_max | qty | quantity less than parameter |
Field Descriptions
underlined fields are required on creation
| Field | Type | Description |
|---|---|---|
| id | int | unique id of item within this business |
| itemid | int | duplicate of id |
| accounting _systemid | string | unique id of business client exists on |
| description | string | descriptive text for item |
| inventory | string | decimal-string count of inventory |
| name | string | descriptive name of item |
| qty | string | decimal-string number to multiply unit cost by |
| sku | string | id for a specific item or product, used in inventory management. Note the sku is not currently available in the FreshBooks UI. |
| tax1 | int | id of default tax for the item |
| tax2 | int | id of second default tax for the item |
| unit_cost | object | subfields: amount and code |
| – amount | string | decimal-string of amount per unit |
| – code | string | three-letter currency code |
| updated | datetime | date item was last updated |
| vis_state | int | 0 for active, 1 for deleted, 2 archived |
Get Single Item
Request: GET https://api.freshbooks.com/accounting/account/<accountid>/items/items/<id>
Response:
{
"response": {
"result": {
"item": {
"itemid": 201225,
"accounting_systemid": "zDmNq",
"updated": "2016-07-20 15:36:09",
"name": "Monkeys",
"qty": "21",
"sku": "FB0192374221",
"inventory": null,
"unit_cost": {
"amount": "1234.00",
"code": "USD"
},
"tax1": 58730,
"vis_state": 0,
"tax2": 58729,
"id": 201225,
"description": "monkey descriptor"
}
}
}
}
Create Single Item
Request: POST "https://api.freshbooks.com/accounting/account/<accountid>/items/items"
{
"item": {
"name": "some item"
}
}
Response:
{
"response": {
"result": {
"item": {
"itemid": 257880,
"accounting_systemid": "zDmNq",
"updated": "2016-09-29 22:05:59",
"name": "some item",
"qty": "0",
"sku": null,
"inventory": null,
"unit_cost": {
"amount": "0.00",
"code": "USD"
},
"tax1": 0,
"vis_state": 0,
"tax2": 0,
"id": 257880,
"description": null
}
}
}
}
Update Single Item
Request: PUT "https://api.freshbooks.com/accounting/account/<accountid>/items/items/<id>"
{
"item": {
"name": "other item"
}
}
Response:
{
"response": {
"result": {
"item": {
"itemid": 257880,
"accounting_systemid": "zDmNq",
"updated": "2016-09-29 22:05:59",
"name": "other item",
"qty": "0",
"sku": "FB0192374221",
"inventory": null,
"unit_cost": {
"amount": "0.00",
"code": "USD"
},
"tax1": 0,
"vis_state": 0,
"tax2": 0,
"id": 257880,
"description": null
}
}
}
}
Delete Single Item
Request: PUT https://api.freshbooks.com/accounting/account/<accountid>/items/items/<id>
{
"item": {
"vis_state": 1
}
}
Response:
{
"response": {}
}
List Items
Request: GET https://api.freshbooks.com/accounting/account/<accountid>/items/items
Response:
{
"response": {
"result": {
"items": [
{
// same format as single item
},
{
// same format as single item
},
{
// same format as single item
}
],
"pages": 1,
"total": 3,
"page": 1,
"per_page": 15
}
}
}
Get Single Item
Request: GET
"https://api.freshbooks.com/accounting/account/<accountid>/items/items/<id>"
url = "https://api.freshbooks.com/accounting/account/<accountid>/items/items/<id>"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = requests.get(url, data=None, headers=headers)
Response:
{
"response": {
"result": {
"item": {
"itemid": 201225,
"accounting_systemid": "zDmNq",
"updated": "2016-07-20 15:36:09",
"name": "Monkeys",
"qty": "21",
"inventory": null,
"unit_cost": {
"amount": "1234.00",
"code": "USD"
},
"tax1": 58730,
"vis_state": 0,
"tax2": 58729,
"id": 201225,
"description": "monkey descriptor"
}
}
}
}
Create Single Item
Request: POST
https://api.freshbooks.com/accounting/account/<accountid>/items/items
url = "https://api.freshbooks.com/accounting/account/<accountid>/items/items"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {
"item": {
"name": "some item"
}
}
res = requests.post(url, data=json.dumps(payload), headers=headers)
Update Single Item
Request: PUT
"https://api.freshbooks.com/accounting/account/<accountid>/items/items/<id>"
url = "https://api.freshbooks.com/accounting/account/<accountid>/items/items/<id>"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {
"item": {
"name": "other item"
}
}
res = requests.put(url, data=json.dumps(payload), headers=headers)
Response:
{
"response": {
"result": {
"item": {
"itemid": 257880,
"accounting_systemid": "zDmNq",
"updated": "2016-09-29 22:05:59",
"name": "other item",
"qty": "0",
"inventory": null,
"unit_cost": {
"amount": "0.00",
"code": "USD"
},
"tax1": 0,
"vis_state": 0,
"tax2": 0,
"id": 257880,
"description": null
}
}
}
}
Delete Single Item
Request: PUT
https://api.freshbooks.com/accounting/account/<accountid>/items/items/<id>
url = "https://api.freshbooks.com/accounting/account/<accountid>/items/items/<id>"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {
"item": {
"vis_state": 1
}
}
res = requests.put(url, data=json.dumps(payload), headers=headers)
Response:
{
"response": {}
}
List items
Request: GET
https://api.freshbooks.com/accounting/account/<accountid>/items/items
url = "https://api.freshbooks.com/accounting/account/<accountid>/items/items"
headers = {'Authorization': 'Bearer <Bearer Token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = requests.get(url, data=None, headers=headers)
Response:
{
"response": {
"result": {
"items": [
{
// same format as single item
},
{
// same format as single item
},
{
// same format as single item
}
],
"pages": 1,
"total": 3,
"page": 1,
"per_page": 15
}
}
}