Category
A Category lets the store owner group his/her products to make the store easier to browse.
Properties
| Property | Explanation |
|---|---|
| id | The unique numeric identifier for the Category |
| name | List of the names of the Category, in every language supported by the store |
| descripton | List of the descriptions of the Category, as HTML, in every language supported by the store |
| handle | List of the url-friendly strings generated from the Category's names, in every language supported by the store |
| parent | Id of the Category's parent. null if it has no parent |
| subcategories | The ids of the Category's first level subcategories |
| google_shopping_category | Attributes used to categorize an item. This category is selected from the Google’s taxonomy. The full list of product categories can be found here: ES - PT |
| created_at | Date when the Category was created in ISO 8601 format |
| updated_at | Date when the Category was last updated in ISO 8601 format |
Endpoints
GET /categories
Receive a list of all Categories.
| Parameter | Explanation |
|---|---|
| since_id | Restrict results to after the specified ID |
| language | Specify search language (required when serching for handle) |
| handle | Show Categories with a given URL |
| parent_id | Show Categories with a given parent category |
| created_at_min | Show Categories created after date (ISO 8601 format) |
| created_at_max | Show Categories created before date (ISO 8601 format) |
| updated_at_min | Show Categories last updated after date (ISO 8601 format) |
| updated_at_max | Show Categories last updated before date (ISO 8601 format) |
| page | Page to show |
| per_page | Amount of results |
| fields | Comma-separated list of fields to include in the response |
GET /categories
HTTP/1.1 200 OK
[
{
"created_at": "2013-01-03T09:11:51-03:00",
"description": {
"en": "",
"es": "",
"pt": ""
},
"handle": {
"en": "poke-balls",
"es": "poke-balls",
"pt": "poke-balls"
},
"id": 4567,
"name": {
"en": "Poké Balls",
"es": "Poké Balls",
"pt": "Poké Balls"
},
"parent": null,
"subcategories": [],
"google_shopping_category": null,
"updated_at": "2013-03-11T09:14:11-03:00"
}
]
GET /categories?fields=id,name,subcategories
HTTP/1.1 200 OK
[
{
"id": 4567,
"name": {
"en": "Poké Balls",
"es": "Poké Balls",
"pt": "Poké Balls"
},
"subcategories": []
}
]
GET /categories/{id}
Receive a single Category
| Parameter | Explanation |
|---|---|
| fields | Comma-separated list of fields to include in the response |
GET /categories/4567
HTTP/1.1 200 OK
{
"created_at": "2013-01-03T09:11:51-03:00",
"description": {
"en": "",
"es": "",
"pt": ""
},
"handle": {
"en": "poke-balls",
"es": "poke-balls",
"pt": "poke-balls"
},
"id": 4567,
"name": {
"en": "Poké Balls",
"es": "Poké Balls",
"pt": "Poké Balls"
},
"parent": null,
"subcategories": [],
"google_shopping_category": null,
"updated_at": "2013-03-11T09:14:11-03:00"
}
POST /categories
Create a new Category
POST /categories
{
"invalid_name": "foobar"
}
HTTP/1.1 422 Unprocessable Entity
{
"name": [
"can't be blank"
]
}
HTTP/1.1 422 Unprocessable Entity
{
"code": 422,
"message": "Unprocessable Entity",
"description": "Store has reached maximum limit of 5000 allowed categories"
}
POST /categories
{
"name": {
"en": "Gen I",
"es": "Gen I",
"pt": "Gen I"
},
"parent": 4567,
"google_shopping_category": "Clothing & Accessories > Jewelry"
}
HTTP/1.1 201 Created
{
"created_at": "2013-06-01T12:15:11-03:00",
"description": {
"en": "",
"es": "",
"pt": ""
},
"handle": {
"en": "gen-i",
"es": "gen-i",
"pt": "gen-i"
},
"id": 5678,
"name": {
"en": "Gen I",
"es": "Gen I",
"pt": "Gen I"
},
"parent": 4567,
"google_shopping_category": "Clothing & Accessories > Jewelry",
"subcategories": [],
"updated_at": "2013-06-01T12:15:11-03:00"
}
PUT /categories/{id}
Modify an existing Category
PUT /categories/5678
{
"id": 5678,
"parent": null
}
HTTP/1.1 200 OK
{
"created_at": "2013-06-01T12:15:11-03:00",
"description": {
"en": "",
"es": "",
"pt": ""
},
"handle": {
"en": "gen-i",
"es": "gen-i",
"pt": "gen-i"
},
"id": 5678,
"name": {
"en": "Gen I",
"es": "Gen I",
"pt": "Gen I"
},
"parent": null,
"subcategories": [],
"google_shopping_category": null,
"updated_at": "2013-06-01T12:15:11-03:00"
}
DELETE /categories/{id}
Remove a Category
DELETE /categories/4567
HTTP/1.1 200 OK
{}
FAQ
How to add categories to a product?
Categories can be added to products through the Product resource. Example:
PUT /products/5123
{
"categories": [1234,4567]
}
What is the character limit of the description property
The maximum amount is 65535 characters.
How to add a child category (subcategory) to an existing category?
A category can be assigned as a child of another category by setting the parent property of the child category to the ID of the parent category. This can be done:
- When creating the child category
- When updating the child category (in case it already exists)
For example, let's suppose that we have a parent category called "Men" (ID 16366393), and we want to create the "Shoes" category inside "Men". We can accomplish this with the following POST request:
POST /categories/
{
"name": {
"es": "Shoes"
},
"parent": 16366393
}
With this request we are not only creating the new "Shoes" category, but also adding it as a subcateogy of "Men".
In case the "Shoes" category already exists, and we want to put it inside the "Men" category, then we can just update it's parent property with the following request:
PUT /categories/{SHOES_CATEGORY_ID}
{
"parent": 16366393
}
Note: The subcategories property is read-only. Therefore, it's not possible to modify that property to assign or remove childs of a parent category. Assignations and removals should be done by setting the parent property of child categories as explained before.