Search categories by path

GET https://app.ecwid.com/api/v3/{storeId}/categoriesByPath?path={path}&delimeter={delimeter}

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

Most query params are optional, only two are required: path and delimeter.

Name
Type
Description

path

string

Full path separated by a delimiter. Spaces around the delimiter and empty path elements are ignored. Required param

delimeter

string

A string of 1 or more characters used as a path delimiter. Required param

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.

hidden_categories

boolean

Set true to include disabled categories.

baseUrl

string

Set base URL for URLs in response. If not specified, Ecwid uses the store URL from general settings.

cleanURLs

boolean

Set true to force receiving clean URLs – catalog links without hashbang (/#!/). If not specified, Ecwid checks URL settings automatically and responds with matching URLs.

slugsWithoutIds

boolean

Set trueto receive category page links without IDs. If not specified, Ecwid checks URL settings automatically and responds with matching URLs.

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:

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

Headers

The Authorization header is required.

Header
Format
Description

Authorization

Bearer secret_ab***cd

Access token of the application.

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

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

Available translations for the category name.

originalImage

Details of the category image.

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

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

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

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

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.

Last updated

Was this helpful?