× Freshbooks App Logo
FreshBooks
Official App
Free - Google Play
Get it

Items

General Info

Items are stored from invoice lines to make invoicing easier in the future.

*Requires Authorization*

Includes

There are no includes to specify for items.

Filters

Filter Type Name Field Description
Equals itemid itemid matches exact itemid
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
itemid int unique id of item within this business
accounting _systemid string unique id of business client exists on
updated datetime date staff object was last updated, YYYY-MM-DD
name string descriptive name of item
qty string decimal-string number to multiply unit cost by
inventory string decimal-string count of inventory
unit_cost object subfields: amount and code
amount string amount paid on invoice, to two decimal places
code string three-letter currency code
tax1 int id of tax on invoice
vis_state int 0 for active, 1 for deleted
tax2 int id of second tax on invoice if applicable
id int duplicate of itemid
description string descriptive text for item
sku string id for a specific item or product, used in inventory management

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/&ltaccountid&gt/items/items/&ltid&gt


url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/items/items/&ltid&gt"
headers = {'Authorization': 'Bearer &ltBearer Token&gt', '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/&ltaccountid&gt/items/items


url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/items/items"
headers = {'Authorization': 'Bearer &ltBearer Token&gt', '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/&ltaccountid&gt/items/items/&ltid&gt


url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/items/items/&ltid&gt"
headers = {'Authorization': 'Bearer &ltBearer Token&gt', '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/&ltaccountid&gt/items/items/&ltid&gt


 url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/items/items/&ltid&gt"
 headers = {'Authorization': 'Bearer &ltBearer Token&gt', '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/&ltaccountid&gt/items/items


url = "https://api.freshbooks.com/accounting/account/&ltaccountid&gt/items/items"
headers = {'Authorization': 'Bearer &ltBearer Token&gt', '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
    }
  }
}