Skip to content
× FreshBooks App Logo
FreshBooks
Official App
Free - Google Play
Get it
You're currently on our US site. Select your regional site here:

Items

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

Access Requirements

AccessRequires Authorization
Scopesuser:billable_items:read
user:billable_items:write

Includes

There are no includes to specify for items.

Filters

Filter TypeNameFieldDescription
Equalsitemiditemidmatches exact itemid
Equalsskuskumatches exact SKU
Initemidsitemidmatches list of itemids, one specified per query arg
Likedescriptiondescriptiondescriptions containing the parameter
Betweenunit_cost_minunit_costunit costs greater than parameter
Betweenunit_cost_maxunit_costunit costs less than parameter
Betweeninventory_mininventoryinventory count greater than parameter
Betweeninventory _maxinventoryinventory count less than parameter
Betweenupdated_minupdateddate greater than or equal to parameter, YYYY-MM-DD format
Betweenupdated_maxupdateddate less than parameter, YYYY-MM-DD format
Betweenqty_minqtyquantity greater than parameter
Betweenqty_maxqtyquantity less than parameter

Field Descriptions

underlined fields are required on creation

FieldTypeDescription
itemidintunique id of item within this business
accounting _systemidstringunique id of business client exists on
updateddatetimedate item was last updated, YYYY-MM-DD
namestringdescriptive name of item
qtystringdecimal-string number to multiply unit cost by
inventorystringdecimal-string count of inventory
unit_costobjectsubfields: amount and code
amountstringamount paid on invoice, to two decimal places
codestringthree-letter currency code
tax1intid of tax on invoice
vis_stateint0 for active, 1 for deleted
tax2intid of second tax on invoice if applicable
idintduplicate of itemid
descriptionstringdescriptive text for item
skustringid for a specific item or product, used in inventory management. Note the sku is not currently available in the FreshBooks UI.

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