Items

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

Access Requirements

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

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/&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
    }
  }
}