Get category

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

Get full category details from an Ecwid store referring to its ID

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.

Query parameters

Field	Type	Description
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 Store SEO
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.

Response

A JSON object of type 'Category' with the following fields:

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
thumbnail	<ImageDetails>	Thumbnail image data. The thumbnail size is specified in the store settings. Resized to fit 400x400px by default
name	string	Category name
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.
productIds	Array<number>	IDs of products assigned to the category as they appear in Ecwid Control Panel > Catalog > Categories
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

Error response example

HTTP/1.1 400 Wrong numeric parameter 'id' value: not a number or a number out of range
Content-Type application/json; charset=utf-8

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`
404	Category is not found
415	Unsupported content-type: expected `application/json` or `text/json`
500	Server error

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

baseUrl parameter is not set in a request:

Example category URL in the url field will be: "https://mdemo.ecwid.com#!/apple/p/70445445"

baseUrl parameter 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.

📘
In order for SEO-friendly (clean) URLs to be enabled on your website, please follow the instructions in SEO-friendly URLs.

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"

cleanUrls parameter is set to false or not set

Example category URL in the url field will be: "https://mdemo.ecwid.com#!/apple/p/70445445"

cleanUrls parameter is set to true

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.