Get category

Request and response example

Request:

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

Response:

{
    "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": 1,
    "productCountWithoutSubcategories": 1,
    "enabledProductCount": 1,
    "description": "",
    "descriptionTranslated": {
        "cs": "",
        "en": ""
    },
    "enabled": true,
    "productIds": [
        692730761
    ],
    "isSampleCategory": false,
    "seoTitle": "Best Toys",
    "seoTitleTranslated": {
        "cs": "",
        "en": "Best Toys"
    },
    "seoDescription": "",
    "seoDescriptionTranslated": {
        "cs": "",
        "en": ""
    },
    "alt": {
        "translated": {}
    }
}

Access scopes

Requires the following access scope: read_catalog

Path params

Param	Type	Description
storeId	number	Ecwid store ID.
categoryId	number	Category ID.

Query parameters

Field	Type	Description
lang	string	Preferred language for the category `name` field 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.
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.

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
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