× 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
idintunique id of item within this business
itemidintduplicate of id
accounting _systemidstringunique id of business client exists on
descriptionstringdescriptive text for item
inventorystringdecimal-string count of inventory
namestringdescriptive name of item
qtystringdecimal-string number to multiply unit cost by
skustringid for a specific item or product, used in inventory management. Note the sku is not currently available in the FreshBooks UI.
tax1intid of default tax for the item
tax2intid of second default tax for the item
unit_costobjectsubfields: amount and code
– amountstringdecimal-string of amount per unit
– codestringthree-letter currency code
updateddatetimedate item was last updated
vis_stateint0 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
    }
  }
}