Permalink
Fetching contributors…
Cannot retrieve contributors at this time
272 lines (173 sloc) 7.08 KB
---
parent: apiv3
title: sku
---
# SKU <%= edit_link %>
A SKU (Stock Keeping Unit) is an aggregation of products.
<%= partial 'partials/toc' %>
## Linked Resources
* <%= link_to 'Linked Resources', '/api/v3#linked-resources' %>
* <%= link_to 'Product', '/api/v3/product' %>
* <%= link_to 'Manufacturer', '/api/v3/manufacturer' %>
## List SKUs of specific category
<pre class="terminal">
GET /categories/:category_id/skus
</pre>
<%= render_recording :category_skus %>
### Ordering
`order_by_methods` returns the available order methods and their human name.
`ordered_by` returns the currenty selected order method.
Name | Type | Value |
----------- | ------ | ----------------------------------------------------------------------- |
`order_by` | String | Any of the available methods returned by `order_by_methods`. Ex: `rank` |
`order_dir` | String | `asc`, `desc` |
> ##### Note
> The default `order_by` & `order_dir` differs across categories
### Meta
You may choose to include extra meta information using the following parameters:
Name | Type | Description
-------------- | ----- | -----------
`include_meta` | Array | Extra meta info to be included in the response
Meta that can be included are:
`available_filters`
: Filters that can be applied
`applied_filters`
: Filters currently applied
<%= render_recording :category_skus_with_available_filters %>
As you can see in the response above the `available_filters` object
contains three objects (<mark>filters</mark>, <mark>manufacturers</mark> and <mark>shops</mark>)
each of which has as keys the ids of the filters that can be applied
and as values the number of SKUs that match the filter.
To retrieve SKUs matching a set of <mark>filters</mark> you have to
add the `filter_ids` parameter which is an array parameter of filter ids, e.g.
`filter_ids[]=1&filter_ids[]=2`.
To retrieve SKUs matching a set of <mark>manufacturers</mark> you have to
add the `manufacturer_ids` parameter which is an array parameter of manufacturer ids, e.g.
`manufacturer_ids[]=1&manufacturer_ids[]=2`.
To retrieve SKUs matching a set of <mark>shops</mark> you have to
add the `shop_ids` parameter which is an array parameter of shop ids, e.g.
`shop_ids[]=1&shop_ids[]=2`.
There also 2 additional objects that can be returned with a slightly different format than the above.
These are <mark>availabilities</mark> and <mark>distances</mark>
To retrieve SKUs within a 2km distance you have to add the `distance` parameter which is the integer value found in the `id` key. e.g. `distance=2`
To retrieve SKUs with immediate availability you have to add the `availability` parameter which is the integer value found in the `id` key. e.g. `availability=2`
### Filtering
#### By search keyword
Name | Type | Description
---- | ------ | -----------
`q` | String | The keyword to search by
<%= render_recording :category_skus_search %>
#### By manufacturers
Name | Type | Description
------------------ | ----- | -----------
`manufacturer_ids` | Array | The ids of the manufacturers of the SKUs
<%= render_recording :category_skus_manufacturers %>
#### By filters
Name | Type | Description
------------ | ----- | -----------
`filter_ids` | Array | The ids of the filters to be applied on the SKUs
<%= render_recording :category_skus_filters %>
<%= render_recording :category_skus_with_applied_filters %>
## Retrieve a single SKU
<pre class="terminal">
GET /skus/:id
</pre>
<%= render_recording :skus_show %>
## Retrieve similar SKUs
<pre class="terminal">
GET /skus/:id/similar
</pre>
<%= render_recording :skus_similar %>
## Retrieve a SKU's reviews
<pre class="terminal">
GET /skus/:id/reviews
</pre>
<%= render_recording :skus_reviews %>
### Meta
You may choose to include extra meta information using the following parameters:
`sku_rating_breakdown`
: Review stats. Each entry contains the star, number of votes and a
percentage to help the client draw a rating bar.
<%= render_recording :sku_reviews_with_rating_breakdown %>
`sku_reviews_aggregation`
: Reviews aggregation. Each entry contains the label, score and
style to help the client choose the color for the bar.
<%= render_recording :sku_reviews_with_aggregation %>
## Vote a SKU's review
> ##### Note
> Requires user token with the 'publish_sku_review_actions' permission.
<pre class="terminal">
POST /skus/:sku_id/reviews/:review_id/votes?vote[helpful]=true|false
</pre>
<%= render_recording :sku_review_vote_create %>
#### Linked resources
The sku review can be included / embedded using the `sku_review` value.
This way, an up-to-date information about the total number of votes / helpful votes
can be received.
<pre class="terminal">
POST /skus/:sku_id/reviews/:review_id/votes?embed=sku_review&vote[helpful]=true|false
</pre>
<%= render_recording :sku_review_vote_create_embed_sku_review %>
## Flag a SKU's review
> ##### Note
> Requires user token with the 'publish_sku_review_actions' permission.
> To retrieve all available flags, see <%= link_to 'Flag', '/api/v3/flag' %>.
Returns empty body, unless an error occurs.
<pre class="terminal">
POST /skus/:sku_id/reviews/:review_id/flags?flag[reason]=bad_language|wrong_section|spam
</pre>
<%= render_recording :sku_review_flag_create %>
## Retrieve a SKU review form
<pre class="terminal">
GET /skus/:id/reviews/new
</pre>
<%= render_recording :skus_reviews_new %>
## Create a new SKU review
<pre class="terminal">
POST /skus/:id/reviews
</pre>
<%= render_recording :skus_reviews_create %>
## Retrieve a SKU review form and it's selected answers
<pre class="terminal">
GET /skus/:id/reviews/:id/edit
</pre>
<%= render_recording :skus_reviews_edit %>
## Update an existing SKU review
<pre class="terminal">
PUT /skus/:id/reviews/:id
</pre>
<%= render_recording :skus_reviews_update %>
## Delete a SKU review
<pre class="terminal">
DELETE /skus/:id/reviews/:id
</pre>
<%= render_recording :skus_reviews_destroy %>
## Retrieve an SKU's specifications
SKU specifications can be retrieved with the following request.
> ##### Note
> Pagination is not available for this endpoint.
<pre class="terminal">
GET /skus/:id/specifications
</pre>
<%= render_recording :sku_specifications %>
The specification group can be included / embedded using the `group` value.
Groups represent a logical grouping of specifications.
<pre class="terminal">
GET /skus/:id/specifications?include=group
</pre>
<%= render_recording :sku_specifications_include_group %>
## Retrieve a SKU's price history
> ##### Note
> Currently this endpoint responds with any available data for the last 6 months, but will not return data for too new SKUs.
<pre class="terminal">
GET /skus/:id/price_history
</pre>
<%= render_recording :skus_price_history %>
## Retrieve an SKU's favorite
> ##### Note
> Requires user token with the 'favorites' permission.
If the SKU has been _favorited_ by the currently associated user, you can fetch it.
<pre class="terminal">
GET /skus/:id/favorite
</pre>
<%= render_recording :sku_favorite %>