Skip to end of metadata
Go to start of metadata

Items are what visitors to the store actually buy.

This page is a work in progress. Until it is finished you may find some extra information in  the old documentation.

Table of contents

URLs

Pattern
Description
Methods allowed
[URL_BASE]/items/listUsed to retrieve lists of items. See below for parameters.GET
[URL_BASE]/items/createUsed to create new items.POST
[URL_BASE]/items/[id]Used to refer to an item based on its Shopamine ID.GET, POST, DELETE
[URL_BASE]/items/by_external_id/[external_id]Used to refer to an item based on its external ID.GET, POST, DELETE
[URL_BASE]/items/by_sku/[sku]Used to refer to an item based on its SKU.GET, POST, DELETE

JSON encoding

These tables are meant as a reference. See full examples on the bottom of the page.

Identifiers

Field
Type
Restrictions
Description
Sample value
idintegerrequired, unique, immutable, auto-generatedShopamine ID of the item. Although you can specify the ID when creating an item, you probably shouldn't.123
external_idstringoptional, unique, immutableExternal ID of the item, for example from an ERP. This field should be used if it is stable, meaning it will never change."152151"
skustringoptional, uniqueSimilar to external_id, but should be used if the value can be changed."CAMLOR0022"

Basic properties

Field
Type
Restrictions
Description
Sample value
namelocalized stringrequiredThe name of the item.
{
  "__": "A steak"
  "sl": "Zrezek"
}
typeenum:
  • "physical"
  • "variants"
requiredThe type of the item. "physical" means the item is a single physical product. "variants" means the item is a container of choices, where the buyer must choose one upon placing the item into basket."physical"
stock_amountintegerrequiredThe quantity of item currently in stock. If missing when creating an item, defaults to 0.67
avail_in_daysintegerrequiredThe approximate number of days in which the item can be obtained, when buying quantities above stock_amount. If missing when creating an item, defaults to 14.3
tax_class_idintegerrequiredThe ID of the Tax class to which this item belongs. If missing when creating an item, defaults to the first defined tax class, but you should not rely on that.1
buyable

enum:

  • "yes"
  • "no"
  • "as_part_only"

required

Determines whether the item can currently be bought. "yes" means the item can be bought stand-alone, "as_part_only" means the item can only be bought as part of something else, for example an item with type "variants", or as a linked item in an option. If missing when creating an item, defaults to "no".

This field will likely change in the future because it is hard to use, however we will do our best to maintain API compatibility.
"yes"
unit_of_salelocalized stringoptionalDescribes what a quantity of 1 is exactly, for example a piece, a package, a box, a meter, ..
{
  "__": "pc",
  "sl": "kos"
}

Quantity restrictions

Field
Type
Restrictions
Description
Sample value
sale_qty_minimumintegeroptional, 1 or more, see belowSpecifies the minimum quantity that can be bought in one purchase. See below for default behavior.10
sale_qty_maximumintegeroptional, 100000 or less, see belowSpecifies the maximum quantity that can be bought in one purchase. See below for default behavior.500
sale_qty_stepintegeroptional, 1..10000, see belowSpecifies the step of the quantity that can be bought. For example, if the item is beer which is only sold in six-packs, this would be 6.1

If set on an item, the values specified apply. If not, and the item is being bought as part of a "variants" item, the settings there are used. If those are also missing, the global store settings are used. The global store settings default to step 1, minimum 1 and maximum 1000.

Minimum and maximum must always be multiples of the step. While API itself doesn't enforce this, the store front-end will round to nearest multiples when necessary.

Maximum should (obviously) be set at or above the minimum. If that is not the case, minimum wins. Again, this is not enforced at the API level, but is enforced by the front-end.

Prices and discounts

Field
Type
Restrictions
Description
Sample value
pricesJSON objectrequiredContains the following three fields.
"prices": {
  "p1": 140.0,
  "p2": 110.0
}
prices.p1decimalrequiredThe first price. What exactly that means is defined in store settings, but usually it is the list price of the item, before taxes and discounts.140.0
prices.p2decimaloptionalThe second price. Also defined in store settings, but when used, it is usually something like a price for resellers or club members.110.0
prices.p3decimaloptionalThe third price. Also defined in store settings, usually not used (one case where it is used is for MSRP).180.0
discountsJSON objectoptionalContains the following three fields. Note that they are not percentages but ratios, so a 25% discount is represented with 0.25.
"discounts": {
  "d1": 0.1,
  "d2": 0.3
}
discounts.d1decimal (ratio)optionalThe first discount. Much like prices, the meaning is defined in store settings, but usually it is the "web discount", meaning the difference between list price and sale price.0.2
discounts.d2decimal (ratio)optionalThe second discount. Also defined in store settings, not typically used.0.3
discounts.d3decimal (ratio)optionalThe third discount. Also defined in store settings, not typically used.0.4

As mentioned in description, these fields can be combined in different ways (as specified in store settings) to produce item prices for buyers. It should be noted that when a store is using External prices service, the values here are basically completely ignored, except as fallback values in case of errors. It should also be noted that these prices (including those from the external service) are still not final - promotions (e.g. coupons) can be applied on top of these "standard" discounts, taxes may be added, and they are subject to rounding settings.

Shipping dimensions

Field
Type
Restrictions
Description
Sample value
shipping_dimensionsJSON objectoptionalContains the following four fields.
"shipping_dimensions": {
  "weight": 1550,
  "width": 100,
  "depth": 150,
  "height": 100
}
shipping_dimensions.weightdecimal (grams)optional, 100000000 or lessContains the net shipping weight, in grams (so the maximum is 100 tons).1550
shipping_dimensions.widthdecimal (mm)optional, 50000 or lessContains the shipping package width, in millimeters (so the maximum is 50 meters).100
shipping_dimensions.depthdecimal (mm)optional, 50000 or lessContains the shipping package depth, in millimeters.130.5
shipping_dimensions.heightdecimal (mm)optional, 50000 or lessContains the shipping package height, in millimeters.51

Note that either all three sizes should be present, or none - there are no 1 or 2-dimensional objects in the real world. Weight can be specified independently and can be used in shipping fee calculation (sizes are not currently used).

Presentational information

Field
Type
Restrictions
Description
Sample value
bar_codestringoptional, uniqueContains the bar code (EAN) of the item."1519593251"
modelstringoptionalContains.. something, like a manufacturer's model id."RT-N7000"
list_desclocalized string (plain text)optionalContains a very short description of the item, used when the item is displayed in a list (like on a category page).{ "__": "The newest widget from Brand" }
short_desclocalized string (HTML)optionalContains a short description of the item, typically displayed somewhere on top of the item page.{ "__": "This is the <i>finest ever</i> widget ... " }
long_desclocalized string (HTML)optionalContains a long description of the item, with all the details etc. Typically displayed on bottom of the item page.{ "__": "<h1>History</h1> The story of widget started way back in ..." }
warranty_monthsintegeroptionalContains the length of the product warranty, in months.60
imagesJSON objectoptionalContains the next three fields.
"images": {
    "gallery": [ 515, 516, 517 ],
    "list": 514,
    "variant_chooser": 922
}
images.galleryarray of image IDsoptionalContains an ordered list of images, shown as the item's gallery on its page. The first image in the list is also used as the default for the next two fields, if they're missing.[ 515, 516, 517 ]
images.listimage IDoptionalUsed as the item's image when displaying it in lists. If missing, defaults to the first image from the gallery.514
images.variant_chooserimage IDoptionalUsed as the item's image, when it is being bought as part of a "variants" item, and that one is configured to display item images for selection.922

Specs

Specs (short for specifications, which are the historical origin of the feature) are generically-defined attributes which items can have. They are used for sorting, filtering and/or simply for being displayed. Before they can be set on an item, they have to be defined using Specs API.

In the Items API they are split into two parts, values and layout. The first is for, well, values, while layout is used to specify how the specs are to be displayed on the front-end. They are split so that values can be updated without having to deal with the display layout. The top level in an item thus looks like:

{
    ...,
    "specs": {
        "values": {
            "spec[id]": value,
            "spec[id]": value,
            ...
        },
        "layout": {
            ...
        }
    }
}

 

The format for a value depends on the type of the spec:

Spec type
Value format
Sample
Numeric{ "number": decimal }{ "values": { "spec12": { "number": 150 } } }
String / textual{ "string": { localized string } }{ "values": { "spec13": { "string": { "__": "2x USB and 1x eSata", "sl": "2 USBja in 1 eSata"  } } } }
Boolean{ "boolean": boolean }{ "values": { "spec14": { "boolean": true } } }
Choice{ "choice_id": integer }{ "values": { "spec15": { "choice_id": 851 } } }

The layout doesn't contain values, but is a list of groups and specs, where groups can recursively contain more groups and specs. Typically, when the number of specs is small, they are simply listed at the top level. When the number of specs is larger, the top level is usually a list of groups, each of which contains a bunch of specs. However, any other structure is fine as well, including deeply nested groups, if they're needed. On front-end, specs without values are removed before being displayed, as are empty groups.

Each group must have a (localized) name, and a list of parts. Each non-group part only has the spec ID:

"layout": [
    { "spec_id": 1 },
    { "spec_id": 2 },
    {
        "group_name": { "__": ... },
        "parts": [
            { "spec_id": 3 },
            { "spec_id": 4 },
            // recursive ...
        ]
    },
    { "spec_id": 5 }
]

Nodes

Items can be in nodes, which can represent (among other things) categories in catalog, brands or generic pages. They are listed separately, so that if the API client only knows about categories (for example), it can manipulate that separately without interfering with other types of nodes. It is all virtual, though, so if you know the full list of node IDs to which an item belongs, you can put them under any type of node and it will work (if you're reading them, though, you'll have to look at all the separate lists).

The order in which nodes are listed in the API is not terribly important, except that the first category is the item's primary in the sense that if you reach the item via some other method than browsing (e.g. search or custom content), it will be shown in that category. Each list can only contain valid node IDs.

"nodes": {
    "categories": [ 1, 2, 3 ],
    "brands": [ 4 ],
    "pages": [ 7, 8 ],
    "finders": [ 9 ]
}

Variants

TODO

Options

TODO

Miscellaneous

Field
Type
Restrictions
Description
Sample value
date_updatedtimestamprequired, auto-generatedContains the timestamp at which the item was last updated via any method. Ignored if specified in input."2015-02-01T23:12:01Z"
date_createdtimestamprequired, auto-generatedContains the timestamp at which the item was first created. Ignored if specified in input."2015-01-01T08:22:15Z"
sys_tagsarray of stringsoptionalContains various tags which might be used by front-end templates to display items differently.[ "new" ]
extra_search_kwslocalized stringoptionalContains extra keywords by which the item can be found using search (not used very often).{ "__": "šraufencigr šraufenciger šraufncigr" }
seo_dataJSON objectoptionalContains the following fields, all with SEO-related information, which is typically not shown to users, but is meant for search engines and the like, instead. 
seo_data.keywordslocalized stringoptionalContains keywords to put in <meta name="keywords"> tag. 
seo_data.descriptionlocalized stringoptionalContains text to put in <meta name="description"> tag. 
seo_data.custom_meta_tagsarray of objectsoptionalCan contain an arbitrary list of other <meta> tags, each of which can have the following three fields. 
seo_data.custom_meta_tags.[...].namestringoptionalValue for name attribute in <meta> 
seo_data.custom_meta_tags.[...].propertystringoptionalValue for property attribute in <meta> 
seo_data.custom_meta_tags.[...].contentlocalized stringoptionalValue for content attribute in <meta> 

 

 

List parameters

These can be used with the .../items/list URL. By default you will receive 10 items and can request up to 40 using limit.

Parameter
Possible values
Description
Examples
order

id
external_id
name
price:p1
price:p2
price:p3
discount:d1
discount:d2
discount:d3
model
sku
bar_code
stock_amount
avail_in_days
date_created
date_updated 

This parameter specifies the sort order to be used, they all correspond to the field with the same name in JSON.

If you wish to specify multiple fields, you can do so by separating them with "," (commas).

To invert the sort order, prefix the field name with a "-" (minus).

.../items/list

By default, items are sorted by id.

.../items/list?order=-date_updated

To find most recently edited items.

.../items/list?order=price:p1,id

To retrieve items by price, least expensive first (maybe to check for items with 0 price). When using fields where multiple items can have the same value, it's a good idea to add id (or something else which is unique) as the last field to ensure consistent pagination.

offset0..10000Used with pagination to skip some number of initial items.

.../items/list?offset=200

Skips first 200 items

limit1..40Used to set the maximum number of items returned.

.../items/list?limit=40

To retrieve first 40 items instead of 10

.../items/list?offset=40&limit=20&order=-date_updated

To retrieve the third page of recently updated items, where page size is 20.

Examples

TODO

  • No labels
Write a comment…