Search categories

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

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": {}
        }
    ]
}

Required access scopes

Your app must have the following access scopes to make this request: read_catalog

Path params

All path params are required.

Param	Type	Description
storeId	number	Ecwid store ID.

Query params

All query params are optional.

Name	Type	Description
keyword	string	Search term for category name and description.
parent	number	Parent category ID. If specified, the response will contain only categories that belong inside the specified one.
parentIds	string	Comma-separated list of parent category identifiers for descendants search. If both parent and parentIds are specified, Ecwid API makes a search using the joined list of category IDs from both fields.
withSubcategories	boolean	Set true to receive full categories structure (subcategories of subcategories, etc.) If false or not specified, only direct descendants of specified category IDs from parent and parentIds parameters are returned.
hidden_categories	boolean	Set true to include disabled categories.
offset	number	Offset from the beginning of the returned items list. Used when the response contains more items than limit allows to receive in one request. Usually used to receive all items in several requests with multiple of a hundred, for example: ?offset=0 for the first request, ?offset=100, for the second request, ?offset=200, for the third request, etc.
limit	number	Limit to the number of returned items. Maximum and default value (if not specified) is 100.
lang	string	Language ISO code for translations in JSON response, e.g. en, fr. Translates fields like: title, description, pickupInstruction, text, etc. If not specified, the default store language is used.
responseFields	string	Specify the exact fields to receive in response JSON. If not specified, the response JSON will have all available fields for the entity. For example: ?responseFields=total,items(id,name,enabled)

Example of using responseFields param:

Request

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

Response

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

Headers

The Authorization header is required.

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

Response JSON

A JSON object with the following fields:

Field	Type	Description
total	number	Total number of found items (might be more than the number of returned items).
count	number	Total number of items returned in the response.
offset	number	Offset from the beginning of the returned items list specified in the request.
limit	number	Maximum number of returned items specified in the request. Maximum and default value: 100.
items	array of objects items	Detailed information about returned 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 and increments by 10.
hdThumbnailUrl	string	Link to the category image resized to fit 800x800px container.
thumbnailUrl	string	Link to the category image resized to fit 400x400px container.
imageUrl	string	Link to the category image resized to fit 1200x1200px container.
originalImageUrl	string	Link to the full-sized category image.
imageExternalId	string	Image ID for Lightspeed R-Series/X-Series image sync. Read-only
name	string	Category name visible on the storefront.
nameTranslated	object translations	Available translations for the category name.
originalImage	object originalImage	Details of the category image.
thumbnail	object thumbnail	Details of the category thumbnail.
origin	string	Internal field that defines category origin inside Lightspeed. One of: LIGHTSPEED ECWID X-SERIES Read-only
url	string	Full URL of the category page on the streofront.
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	Category description in HTML format.
descriptionTranslated	object translations	Available translations for the 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 alt	Alt texts of a category image.
externalReferenceId	string	Internal field for Lightspeed X-Series connection.

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

alt

Field	Type	Description
main	string	Image description for the "alt" HTML attribute of the image.
translations	object translations	Available translations for the "alt" text.

translations

Object with text field translations in the "lang": "text" format, where the "lang" is an ISO 639-1 language code. For example:

{
    "en": "Sample text",
    "nl": "Voorbeeldtekst"
}

Translations are available for all active store languages. Only the default language translations are returned if no other translations are provided for the field. Find active store languages with GET /profile request > languages > enabledLanguages.