Search or filter categories in a store catalog. The response provides basic details of found categories.
The order of categories in response sometimes does not represent their order in the Ecwid Control Panel or storefront. To have categories in that order, check the orderBy field value for each category returned by Ecwid and use it as a sort index in your application.
Headers
| Name | Type | Description |
|---|---|---|
| Authorization | string | oAuth token with mandatory Bearer before it. Example: Bearer e***s0, where e***s0 should be replaced with your oAuth token. |
All query params
| Query field | Type | Description |
|---|---|---|
| offset | number | Offset from the beginning of the returned items list (for paging) |
| limit | number | Maximum number of returned items. Maximum allowed value: 100. Default value: 100 |
| parent | number | ID of the parent category. Set to 0 to get the list of root categories. Leave empty to get all store categories. |
| productIds | boolean | Set to true if you want the results to contain a list of product IDs assigned to category. false is default |
| hidden_categories | boolean | By default, Ecwid returns only enabled categories. Set this parameter to true if you want hidden (disabled) categories to be returned. false is default |
| baseUrl | string | Storefront URL for Ecwid to use when returning category URLs in the url field. If not specified, Ecwid will use the storefront URL specified in the Store profile |
| cleanUrls | boolean | If true, Ecwid will return the SEO-friendly clean URL (without hash '#') in the url field. If false, Ecwid will return URL in the old format (with hash '#'). We recommend using true value if merchant's website supports clean SEO-friendly URLs |
| lang | string | Preferred language for the category fields in search results. If a certain field does not have the translation available for the set language, the default language text will be used for that field. |
Response
A JSON object of type 'CategorySearchResult' with the following fields:
SearchResult
| Field | Type | Description |
|---|---|---|
| total | number | The total number of found items (might be more than the number of returned items) |
| count | number | The total number of the items returned in this batch |
| offset | number | Offset from the beginning of the returned items list (for paging) |
| limit | number | Maximum number of returned items. Maximum allowed value: 100. Default value: 100 |
| items | Array | The categories list |
Category
| Field | Type | Description |
|---|---|---|
| id | number | Internal unique category ID |
| parentId | number | ID of the parent category, if any |
| orderBy | number | Sort order of the category in the parent category subcategories list |
| hdThumbnailUrl | string | Category HD thumbnail URL resized to fit 800x800px |
| thumbnailUrl | string | Category thumbnail URL. The thumbnail size is specified in the store settings. Resized to fit 400x400px by default |
| imageUrl | string | Category image URL. A resized original image to fit 1500x1500px |
| originalImageUrl | string | Link to the original (not resized) category image |
| originalImage | <ImageDetails> | Details of the category image |
| name | string | Category name |
| thumbnail | <ImageDetails> | Thumbnail image data. The thumbnail size is specified in the store settings. Resized to fit 400x400px by default |
| nameTranslated | <Translations> | Available translations for category name |
| origin | string | Read-only field returns if a category originated outside of Ecwid, e.g. "origin": "LIGHTSPEED" |
| url | string | URL of the category page in the store |
| productCount | number | Number of products in the category and its subcategories. Important: if new products are assigned or unassigned for this category, the changes to productCount value will apply after several minutes. |
| enabledProductCount | number | Number of enabled products in the category (excluding its subcategories) |
| description | string | The category description in HTML |
| descriptionTranslated | <Translations> | Available translations for category description |
| enabled | boolean | true if the category is enabled, false otherwise. Use hidden_categories in request to get disabled categories |
| productIds | Array<number> | IDs of products assigned to the category as they appear in Ecwid Control Panel > Catalog > Categories. To make this field appear in a response, send productIds=true in a request. |
| seoTitle | string | Page title to be displayed in search results on the web. Recommended length is under 55 characters. Is empty if value wasn't changed by merchant from the product itself |
| seoTitleTranslated | string | Translations of the page title to be displayed in search results on the web |
| seoDescription | string | Page description to be displayed in search results on the web. Recommended length is under 160 characters. Is empty if value wasn't changed by merchant from the product itself |
| seoDecriptionTranslated | string | Translations of the page description to be displayed in search results on the web |
ImageDetails
| Field | Type | Description |
|---|---|---|
| url | string | Image URL |
| width | integer | Image width |
| height | integer | Image height |
Translations
| Field | Type | Description |
|---|---|---|
| <ISO_LANG_CODE> | string | Translations for each available language. If no other translations are provided, the default language translations is returned. See available languages in store language settings |
Errors
In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description
HTTP codes
| HTTP Status | Meaning | Code (optional) |
|---|---|---|
| 400 | Request parameters are malformed | |
| 400 | The cleanUrls value is invalid. It must be either true or false | CLEAN_URLS_PARAMETER_IS_INVALID |
| 415 | Unsupported content-type: expected application/json or text/json | |
| 500 | Cannot retrieve the categories info because of an error on the server |
Error response body (optional)
| Field | Type | Description |
|---|---|---|
| errorMessage | string | Error message |
Q: How to get URLs for categories?
Direct URL for each category is always available in the url field once you make a request to the Ecwid REST API.
In any Ecwid store there is a Store profile field, where store owners can specify their storefront location. In case if it's empty, Ecwid will use their Instant site URL to provide category URLs in the REST API and other connected services.
When a store is embedded into multiple websites
For this situation you may need to generate a category feed for each of those websites (building a sitemap, etc.), hence there will be multiple storefront URLs to process. In this case you can use baseUrl request parameter to get a working category URL in a response from the Ecwid REST API.
Let's see how it works:
If baseUrl request parameter is specified, then the url field will be generated according to that URL as a storefront URL.
Examples
Ecwid store has a storefront URL set in store settings as: "https://mdemo.ecwid.com":
baseUrlparameter is not set in a request:
Example category URL in the url field will be: "https://mdemo.ecwid.com#!/apple/p/70445445"
baseUrlparameter is set as"https://mycoolstore.com":
Example category URL in the url field will be: "https://mycoolstore.com#!/apple/p/70445445"
As you can see, the category URL in a response from Ecwid API changes based on the value of the baseUrl request parameter. So now you can use it to get category URLs of the same store for any number of storefront URLs.
It is possible to use the baseUrl parameter together with the cleanUrls parameter. See below for more details on the cleanUrls parameter.
Receiving SEO-friendly (clean) URLs from the Ecwid REST API
By default, Ecwid's category URLs use hash-based format: "https://mdemo.ecwid.com#!/apple/p/70445445". In case a website supports the SEO-friendly URLs, you will need to use the cleanUrls request parameter in order to get URLs in that format.
Let's see how it works:
If cleanUrls request parameter is set to true, then url field will have the SEO-friendly format in the response (clean URL, no hash "#").
Examples
Ecwid store has a storefront URL set in store settings as: "https://mdemo.ecwid.com"
cleanUrlsparameter is set tofalseor not set
Example category URL in the url field will be: "https://mdemo.ecwid.com#!/apple/p/70445445"
cleanUrlsparameter is set totrue
Example category URL in the url field will be: "https://mdemo.ecwid.com/apple-p70445445"
As you can see, the format of a category URL returned from the Ecwid API changes based on the cleanUrls request parameter. So now you can use it to get URLs of any of the two supported URL formats - SEO-friendly (clean) URLs or hash-based URLs.
It is possible to use the cleanUrls parameter together with the baseUrl parameter. See above for more details on the baseUrl parameter.