Search categories

get https://app.ecwid.com/api/v3/{storeId}/categories

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.

Request and response example

Request:

curl --location 'https://app.ecwid.com/api/v3/1003/categories' \
--header 'Authorization: Bearer secret_ab***cd'

Response:

{
    "total": 1,
    "count": 1,
    "offset": 0,
    "limit": 100,
    "items": [
        {
            "id": 172786255,
            "orderBy": 10,
            "hdThumbnailUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4519581925.jpg",
            "thumbnailUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4519581924.jpg",
            "originalImageUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4519581923.jpg",
            "imageUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4519581926.jpg",
            "originalImage": {
                "url": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4519581923.jpg",
                "width": 225,
                "height": 225
            },
            "thumbnail": {
                "url": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4519581924.jpg",
                "width": 225,
                "height": 225
            },
            "borderInfo": {
                "dominatingColor": {
                    "red": 255,
                    "green": 255,
                    "blue": 255,
                    "alpha": 255
                },
                "homogeneity": true
            },
            "name": "Best Toys",
            "nameTranslated": {
                "cs": "",
                "en": "Best Toys"
            },
            "url": "https://store1003.company.site/products/toys",
            "autogeneratedSlug": "best-toys",
            "customSlug": "toys",
            "productCount": 0,
            "description": "",
            "descriptionTranslated": {
                "cs": "",
                "en": ""
            },
            "enabled": true,
            "isSampleCategory": false,
            "seoTitle": "Best Toys",
            "seoTitleTranslated": {
                "cs": "",
                "en": "Best Toys"
            },
            "seoDescription": "",
            "seoDescriptionTranslated": {
                "cs": "",
                "en": ""
            },
            "alt": {}
        }
    ]
}

Access scopes

Requires the following access scope: read_catalog

Path params

Param	Type	Description
storeId	number	Ecwid store ID.

Query params

All query params are optional.

Param	Type	Description
keyword	string	Search term for category name and description.
parent	number	Parent category ID. Supports multiple values. For example, `0,12345,23456`.
hidden_categories	boolean	Set to `true` to include disabled categories.
returnProductIds	boolean	Set to `true` to include product IDs.
baseUrl	string	Set base URL for URLs in response. If not specified, Ecwid will use main URL from store settings.
cleanUrls	boolean	Set `true` to force receiving clean URLs – catalog links without hashbang (`/#!/`). By default Ecwid checks if this setting is enabled for the store and responds with matching URLs.
slugsWithoutIds	boolean	Set `true` to receive product page slugs without IDs. By default Ecwid checks if this setting is enabled for the store and responds with matching URLs.
offset	number	Set offset from the beginning of the returned items list by a margin of 100 (for paging).
limit	number	Maximum number of returned items. Default value: `100`. Maximum allowed value: `1000`.
lang	string	Language ISO code for translations in JSON response, e.g. `en`, `fr`. Translates fields like: `title`, `description`, `pickupInstruction`, `text`, etc.
responseFields	string	Limit JSON response by specific fields. If specified, all missing fields will be removed from the response body. Example: `?responseFields=total,items(id,name,enabled)`

Example of using responseFields param:

curl --location 'https://app.ecwid.com/api/v3/1003/categories?responseFields=total,items(id,name,enabled)' \
--header 'Authorization: Bearer secret_ab***cd'

{
    "total": 1,
    "items": [
        {
            "id": 172786255,
            "name": "Best Toys",
            "enabled": true
        }
    ]
}

Headers

The Authorization header with a secret access token is required.

Header	Format	Description
Authorization	`Bearer secret_ab***cd`	Access token of the application.

Response

A JSON object with the following fields:

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: `1000`. Default value: `100`
items	Array items	Details about found categories.

items

Field	Type	Description
id	number	Internal unique category ID.
parentId	number	ID of the parent category, if any.
orderBy	number	Sorting order of the category. Starts from `10`. increments by `10`.
hdThumbnailUrl	string	URL for category thumbnail resized to fit 800x800px.
thumbnailUrl	string	URL for category thumbnail. Resized to fit 400x400px by default.
imageUrl	string	URL for category image. A resized original image to fit 1500x1500px.
originalImageUrl	string	URL for the original category image. Not resized.
imageExternalId	string	Image ID for Lightspeed R-Series/X-Series image sync. Read-only
name	string	Category name.
nameTranslated	Object translations	Available translations for category name
originalImage	Object originalImage	Details of the category image.
thumbnail	Object thumbnail	Details of the category thumbnail.
origin	string	Category origin. Exists only for categories synced outside of Ecwid, e.g. `"origin": "LIGHTSPEED"` Read-only
url	string	URL of the category page in the store.
autogeneratedSlug	string	Autogenerated slug for the category page URL.
customSlug	string	Custom slug for the category page URL.
productCount	number	Number of products in the category and its subcategories. When the product count in the category changes, `productCount` value will update in several minutes.
enabledProductCount	number	Number of enabled products in the category (excluding any subcategories). Requires the `productIds=true` query param.
description	string	The category description in HTML.
descriptionTranslated	Object 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 of numbers	IDs of products assigned to the category as they appear in Ecwid admin > Catalog > Categories. Requires `productIds=true` query param.
seoTitle	string	SEO page title for web search results. Recommended length is under 55 characters.
seoTitleTranslated	string	SEO page title translations.
seoDescription	string	SEO page description for web search results. Recommended length is under 160 characters.
seoDecriptionTranslated	string	SEO page description translations.
alt	Object alts	Alt texts of a category image.

originalImage

Field	Type	Description
url	string	Image URL
width	integer	Image width
height	integer	Image height

thumbnail

Field	Type	Description
url	string	Image URL
width	integer	Image width
height	integer	Image height

alts

Field	Type	Description
main	string	The original alt text attached to a category image
<ISO_LANG_CODE>	string	Translations for each available language.

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