Price List Items

Minimum access level: Invoices, Estimates and Files

Attributes

Required	Attribute	Description	Kind
	url	The unique identifier for the price list item	URI
✔	code	A unique name / code used to identify the item when adding it to an invoice or estimate	String
✔	quantity	Item quantity	Decimal
✔	item_type	One of the following: `Hours` `Days` `Weeks` `Months` `Years` `Products` `Services` `Training` `Expenses` `Comment` `Bills` `Discount` `Credit` `VAT` `Stock`	String
✔	description	Free-text description of the item	String
✔	price	The unit price of one item	Decimal
	vat_status	[UK accounts only] One of the following: `out_of_scope` (default) `reduced` `standard` `zero`	String
	sales_tax_rate	[Universal and US accounts only] One of the standard sales tax rates	Decimal
	second_sales_tax_rate	[Universal accounts only] One of the standard second sales tax rates	Decimal
	category	Income accounting category of the item	URI
	stock_item	Stock item, if `item_type` is stock	URI
	created_at	Creation of the price list item (UTC)	Timestamp
	updated_at	When the price list item was last updated (UTC)	Timestamp

List all price list items

GET https://api.freeagent.com/v2/price_list_items

Sort Orders

GET https://api.freeagent.com/v2/price_list_items?sort=created_at

created_at: Sort by the time the price list item was created (default).
code: Sort by the price list item code.
updated_at: Sort by the time the price list item was updated.

To sort in descending order, the sort parameter can be prefixed with a hyphen.

GET https://api.freeagent.com/v2/price_list_items?sort=-created_at

Response

{
  "price_list_items": [
    {
      "url": "https://api.freeagent.com/v2/price_list_items/1",
      "code": "A001",
      "item_type": "Products",
      "quantity": "1.0",
      "price": "10.99",
      "description": "Apple",
      "sales_tax_rate": "0.0",
      "second_sales_tax_rate": "0.0",
      "vat_status": "standard",
      "category": "https://api.freeagent.com/v2/categories/2",
      "created_at":"2023-05-22T09:22:45Z",
      "updated_at":"2023-05-25T12:43:36Z"
    }
  ]
}

Show as XML

<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <price-list-items type="array">
    <price-list-item>
      <url>https://api.freeagent.com/v2/price_list_items/1</url>
      <code>A001</code>
      <item-type>Products</item-type>
      <quantity>1.0</quantity>
      <price>10.99</price>
      <description>Apple</description>
      <sales-tax-rate>0.0</sales-tax-rate>
      <second-sales-tax-rate>0.0</second-sales-tax-rate>
      <vat-status>standard</vat-status>
      <category>https://api.freeagent.com/v2/categories/2</category>
      <created-at type="datetime">2023-05-22T09:22:45Z</created-at>
      <updated-at type="datetime">2023-05-25T12:43:36Z</updated-at>
    </price-list-item>
  </price-list-items>
</freeagent>

Show as JSON

Get a single price list item

GET https://api.freeagent.com/v2/price_list_items/:id

Response

Status: 200 OK

{
  "price_list_item": {
    "url": "https://api.freeagent.com/v2/price_list_items/1",
    "code": "A001",
    "item_type": "Products",
    "quantity": "1.0",
    "price": "10.99",
    "description": "Apple",
    "sales_tax_rate": "0.0",
    "second_sales_tax_rate": "0.0",
    "vat_status": "standard",
    "category": "https://api.freeagent.com/v2/categories/2",
    "created_at":"2023-05-22T09:22:45Z",
    "updated_at":"2023-05-25T12:43:36Z"
  }
}

Show as XML

<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <price-list-item>
    <url>https://api.freeagent.com/v2/price_list_items/1</url>
    <code>A001</code>
    <item-type>Products</item-type>
    <quantity>1.0</quantity>
    <price>10.99</price>
    <description>Apple</description>
    <sales-tax-rate>0.0</sales-tax-rate>
    <second-sales-tax-rate>0.0</second-sales-tax-rate>
    <vat-status>standard</vat-status>
    <category>https://api.freeagent.com/v2/categories/2</category>
    <created-at type="datetime">2023-05-22T09:22:45Z</created-at>
    <updated-at type="datetime">2023-05-25T12:43:36Z</updated-at>
  </price-list-item>
</freeagent>

Show as JSON

Create a price list item

POST https://api.freeagent.com/v2/price_list_items

Payload should have a root price_list_item element, containing elements listed under Attributes.

Example Request Body

{
  "price_list_item": {
    "code": "A001",
    "description": "Apple",
    "vat_status": "standard",
    "price": "1.99",
    "item_type": "Products",
    "quantity": "1"
  }
}

Show as XML

<?xml version="1.0" encoding="UTF-8"?>
<price-list-item>
  <code>A001</code>
  <description>Apple</description>
  <vat-status>standard</vat-status>
  <price type="decimal">1.99</price>
  <item-type>Products</item-type>
  <quantity type="decimal">1</quantity>
</price-list-item>

Show as JSON

Response

Status: 201 Created
Location: https://api.freeagent.com/v2/price_list_items/17

{
  "price_list_item": {
    "category": "https://api.freeagent.com/v2/categories/001",
    "code": "A001",
    "vat_status": "standard",
    "description": "Apple",
    "url": "https://api.freeagent.com/v2/price_list_items/17",
    "sales_tax_rate": "0.0",
    "price": "1.99",
    "item_type": "Products",
    "second_sales_tax_rate": "0.0",
    "quantity": "1.0",
    "created_at":"2023-05-25T12:43:36Z",
    "updated_at":"2023-05-25T12:43:36Z"
  }
}

Show as XML

<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <price-list-item>
    <url>https://api.freeagent.com/v2/price_list_items/17</url>
    <code>A001</code>
    <item-type>Products</item-type>
    <quantity type="decimal">1.0</quantity>
    <price type="decimal">1.99</price>
    <description>Apple</description>
    <sales-tax-rate type="decimal">0.0</sales-tax-rate>
    <second-sales-tax-rate type="decimal">0.0</second-sales-tax-rate>
    <vat-status>standard</vat-status>
    <category>https://api.freeagent.com/v2/categories/001</category>
    <created-at type="datetime">2023-05-25T12:43:36Z</created-at>
    <updated-at type="datetime">2023-05-25T12:43:36Z</updated-at>
  </price-list-item>
</freeagent>

Show as JSON

Update a price list item

PUT https://api.freeagent.com/v2/price_list_items/:id

Payload must have a root price_list_item element, containing elements listed under Attributes that should be updated.

Example Request Body

{
  "price_list_item": {
    "description": "Pear",
    "price": "3.99"
  }
}

Show as XML

<?xml version="1.0" encoding="UTF-8"?>
<price-list-item>
  <description>Pear</description>
  <price type="decimal">3.99</price>
</price-list-item>

Show as JSON

Response

Status: 200 OK

Delete a price list item

DELETE https://api.freeagent.com/v2/price_list_item/:id

Response

Status: 200 OK