Items
Items can be accessed through the API via the items base URL:
$ curl https://app.handshake-app.com/api/v2/items
- Supported list methods:
GETPOST - Supported detail methods:
GETPUTDELETE
Fields
item.sku (string) [required]
The SKU or "product code" of the item. This must be unique within your account; you cannot have two
items with the same sku.
item.name (string) [required]
item.longDesc (string)
item.barcode (string)
item.unitPrice (decimal) [required]
The price for a single unit of this Item. Even if the multQty of this product is greater than 1
(i.e. it is only sold in case packs), this always represents the cost of a single unit of the Item, not the cost of a case pack.
A By default, this is the "base" unit price of the Item, however, the pricesForCustomer query
parameter (see below) can be used to cause a GET to return the pricing that is applicable to a
particular Customer.
item.minQty (integer) [required]
The minimum quantity of this Item that can be ordered. If you allow customers to order just one
unit of this product, then this should be 1.
item.multQty (integer) [required]
The multiple quantity of this Item (i.e. the case pack). If you allow customers to order single
units of the product, then this should be 1.
item.category (reference to Category) [required]
The Category that this product is in.
item.categoryPosition (integer)
The position of this item in its category. If this is not provided when a new item is created via
the API, the system will default it to be at the end of the category (i.e. one higher than all the
existing items).
item.variants (collection of Variants)
The variants of this item (e.g. variations on color or size or similar).
item.dimensions (readonly dictionary)
For items that have variants, this dictionary will be a mapping of product dimensions (e.g. 'Color',
'Size' etc) to the supported values for those dimensions. This is a convenience parameter and allows you to figure out the set of product dimensions without having to traverse the variants
collection and figure it out for yourself.
For example:
{
'Color': ['Blue', 'Green', 'Red'],
'Size', ['4', '6', '8', '10', '12']
}
item.addtionalPrices (dictionary)
A dictionary mapping CustomerGroup IDs to prices specific to those customer groups.
For example, if there was a customer group with ID "UK" and the price for an item in that customer group was 12.34, this dictionary would contain:
{
'UK': "12.34",
}
item.manufacturer (readonly reference to Manufacturer)
The Manufacturer of this product, whether this is an
additional manufacturer or the company itself. This is never null.
This field is read-only because it is actually derived from the Category that this Item belongs to; the Item does itself have a direct relationship to the Manufacturer.
item.imageURLs (list of strings)
This property provides a method of both reading and writing the list of images that are attached to
this item.
These URLs are useful for including links to images in confirmation emails, although you should
probably avoid including these images directly in the email because they could be large and will
render slowly when your customer reads your email. You should use thumbnailURLs below for
including images directly in emails.
When fetched via GET this property will simply return the public URLs of the images for this
product (these are the ones that are embedded in order confirmation emails to your customers,
amongst other things).
When written to via POST or PUT, any image URLs you include in this list which do not already
exist in Handshake (i.e. are not already attached to an existing item) will be downloaded from the
internet, scaled as per the normal rules, and attached to the item.
item.thumbnailURLs (readonly list of strings)
This property provides the URLs of the 48x48 thumbnails that correspond to the images in imageURLs
above. This property is readonly because you cannot upload thumbnails directly; they are
auto-generated as part of the import process when you POST or PUT new values for imageURLs.
Because these are very small, they are appropriate for including images in confirmation emails, e.g.
<img src="{{ item.thumbnailURL }}" />
item.imageURL (readonly string)
The first entry from imageURLs above. Useful when you just want access to the primary image on
a particular item.
item.thumbnailURL (readonly string)
The first entry from thumbnailURLs above. Useful when you just want access to the primary
thumbnail on a particular item.
Filters
category (integer)
If you pass category=<objID> as a request parameter, with the objID of a Category as a filter, only items contained in that category or one of its subcategories will be returned.
manufacturer (integer)
If you pass manufacturer=<objID> as a request parameter, with the objID of a Manufacturer as a filter, only items that belong to that manufacturer will
be returned.
order (integer)
If you pass order=<objID> as a request parameter, with the objID of an Order as a filter, only items that are on that order will be returned.
search (string)
If you pass search=<needle> as a request parameter, only items with a sku or name that
contains the needle will be returned.
sku (string)
Filters items by an exact match on sku. When applying this filter you will get either 0 or 1
results.
# Filter for the item with SKU 'BAG123'
$ curl https://app.handshake-app.com/api/v2/items?sku=BAG123
pricesForCustomer (integer)
If you pass pricesForCustomer=<objID> as a request parameter with the objID of a Customer, the unitPrice field in the results will return the pricing
that is applicable to that customer, rather than the base unit price defined for the Item.
This isn't so much a "filter" as a "modifier", since it does not change which Items are returned in
the response.
Example
{
"barcode": "9780375766133",
"category": {
"id": "/BL/Woodwinds/Saxophones",
"manufacturer": "/api/v2/manufacturers/949",
"name": "Saxophones",
"objID": 959,
"parent": "/api/v2/categories/958",
"resource_uri": "/api/v2/categories/959",
"subType": "Item",
"subcategories": []
},
"categoryPosition": 1,
"cdate": "2010-10-06",
"ctime": "2010-10-06T21:02:20Z",
"dimensions": null,
"entityType": "Item",
"imageURL":
"http://c496639.r39.cf2.rackcdn.com/image/35dbf08257af8710c74a43b061...",
"imageURLs": [
"http://c496639.r39.cf2.rackcdn.com/image/35dbf08257af8710c74a43b061bc13e3ccec08cd.jpg",
"http://c496639.r39.cf2.rackcdn.com/image/09841d58cb3495ffac082c78654614ab1f82cae4.png",
"http://c496639.r39.cf2.rackcdn.com/image/af4303a95b6531d42a85d6c3ed3eebec4cf1caa4.jpg"
],
"longDesc": "You can use this long description field on each item to store extended product
information.It can span multiple lines and it can be as long as you like.",
"minQty": 1,
"mtime": "2012-02-01T17:30:25Z",
"multQty": 1,
"name": "Alto Saxophone",
"objID": 27,
"owner": "Demo",
"resource_uri": "/api/v2/items/27",
"sku": "SAX.A",
"thumbnailURL":
"http://c496639.r39.cf2.rackcdn.com/thumb_48/35dbf08257af8710c74a43b...",
"thumbnailURLs": [
"http://c496639.r39.cf2.rackcdn.com/thumb_48/35dbf08257af8710c74a43b061bc13e3ccec08cd.jpg",
"http://c496639.r39.cf2.rackcdn.com/thumb_48/09841d58cb3495ffac082c78654614ab1f82cae4.png",
"http://c496639.r39.cf2.rackcdn.com/thumb_48/af4303a95b6531d42a85d6c3ed3eebec4cf1caa4.jpg"
],
"unitPrice": "1495.00",
"uuid": "18616a19-6508-42d6-9e32-bbc10537a385",
"variants": []
}