NAV

Categories

Using the methods below you can search/get/update/delete categories in an Ecwid store. It is possible to change the category name, its products, image and more.

Get 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

Request example

GET /api/v3/4870020/categories?hidden_categories=true&token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/categories?parent={parent}&hidden_categories={hidden_categories}&offset={offset}&limit={limit}&productIds={productIds}&baseUrl={baseUrl}&cleanUrls={cleanUrls}&token={token}

Query fieldTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 100
parentnumberID of the parent category. Set to 0 to get the list of root categories. Leave empty to get all store categories.
hidden_categoriesbooleanBy default, Ecwid returns only enabled categories. Set this parameter to true if you want hidden (disabled) categories to be returned. false is default
productIdsbooleanSet to true if you want the results to contain a list of product IDs assigned to category. false is default
baseUrlstringStorefront 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 settings
cleanUrlsbooleanIf 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 SEO-friendly URL feature

Response

Response example

{
    "total": 2,
    "count": 2,
    "offset": 0,
    "limit": 100,
    "items": [
        {
            "id": 9691094,
            "orderBy": 10,
            "hdThumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/397690775.jpg",
            "thumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/123412341234.jpg",
            "imageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/images/1003/461717703.jpg",
            "originalImageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124125.jpg",
            "originalImage": {
                "url": "https://app.ecwid.com/default-store/fruit-230-sq.jpg",
                "width": 123,
                "height": 456
            },            
            "name": "Fruit",
            "url": "http://app.ecwid.com/store/4870020#!/Fruit/c/9691094",
            "productCount": 6,
            "enabledProductCount": 5,
            "description": "",
            "enabled": true
        },
        {
            "id": 9691095,
            "orderBy": 20,
            "hdThumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/397690772.jpg",
            "thumbnailUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/123412341254.jpg",
            "imageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/images/1003/461717702.jpg",
            "originalImageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124124.jpg",
            "originalImage": {
                "url": "https://dqzrr9k4bjpzk.cloudfront.net/1003/124124124.jpg",
                "width": 123,
                "height": 456
            },
            "name": "Vegetables",
            "url": "http://app.ecwid.com/store/4870020#!/Vegetables/c/9691095",
            "productCount": 4,
            "enabledProductCount": 3,
            "enabled": false
        }
    ]
}

Public token request example

GET /api/v3/4870020/categories?hidden_categories=true&token=public_123abcdaASasdASjndasAnsdu HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

Response example

{
    "total": 2,
    "count": 2,
    "offset": 0,
    "limit": 100,
    "items": [
        {
            "id": 9691094,
            "orderBy": 10,
            "hdThumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/397690775.jpg",
            "thumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/12321312.jpg",
            "imageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/images/1003/461717702.jpg",
            "originalImageUrl": "https://dpbfm6h358sh7.cloudfront.net/1003/1231231231.jpg",
            "originalImage": {
                "url": "https://app.ecwid.com/default-store/fruit-230-sq.jpg",
                "width": 123,
                "height": 456
            },            
            "name": "Fruit",
            "url": "http://app.ecwid.com/store/4870020#!/Fruit/c/9691094",
            "productCount": 6,
            "enabledProductCount": 5,
            "description": "",
            "enabled": true
        },
        {
            "id": 9691095,
            "enabled": false
        }
    ]
}

A JSON object of type ‘SearchResult’ with the following fields:

SearchResult

FieldTypeDescription
totalnumberThe total number of found items (might be more than the number of returned items)
countnumberThe total number of the items returned in this batch
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 100
itemsArrayThe categories list

Category

FieldTypeDescription
idnumberInternal unique category ID
parentIdnumberID of the parent category, if any
orderBynumberSort order of the category in the parent category subcategories list
hdThumbnailUrlstringCategory HD thumbnail URL resized to fit 800x800px
thumbnailUrlstringCategory thumbnail URL. The thumbnail size is specified in the store settings. Resized to fit 400x400px by default
imageUrlstringCategory image URL. A resized original image to fit 1500x1500px
originalImageUrlstringLink to the original (not resized) category image
originalImage<ImageDetails>Details of the category image
namestringCategory name
urlstringURL of the category page in the store. Learn more
productCountnumberNumber of products in the category and its subcategories
enabledProductCountnumberNumber of enabled products in the category (excluding its subcategories)
descriptionstringThe category description in HTML
enabledbooleantrue if the category is enabled, false otherwise. Use hidden_categories in request to get disabled categories
productIdsArray<number>IDs of products assigned to the category as they appear in Ecwid Control Panel > Catalog > Categories

ImageDetails

FieldTypeDescription
urlstringImage URL
widthintegerImage width
heightintegerImage height

Errors

Error response example

HTTP/1.1 500 Server Error
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 StatusMeaningCode (optional)
400Request parameters are malformed
400The cleanUrls value is invalid. It must be either true or falseCLEAN_URLS_PARAMETER_IS_INVALID
415Unsupported content-type: expected application/json or text/json
500Cannot retrieve the categories info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

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 storefront URL field, where store owners can specify their storefront location. In case if it’s empty, Ecwid will use their starter 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 if a website supports the SEO-friendly (clean) URLs, you will need to use the cleanUrls request parameter in order to get URLs in that format.

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.

Get category

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

Request example

GET /api/v3/4870020/categories/10861116?token=abcdn339900932 HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/categories/{categoryId}?token={token}&baseUrl={baseUrl}&cleanUrls={cleanUrls}

Query fieldTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
categoryIdnumberInternal category ID
baseUrlstringStorefront 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 settings
cleanUrlsbooleanIf 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 SEO-friendly URL feature

Response

Response example

{
    "id": 10861116,
    "parentId": 9691094,
    "orderBy": 20,
    "hdThumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/397690775.jpg",
    "thumbnailUrl": "https://dpbfm6h358sh7.cloudfront.net/images/1003/12321312.jpg",
    "imageUrl": "https://dqzrr9k4bjpzk.cloudfront.net/images/1003/461717702.jpg",
    "originalImageUrl": "https://dpbfm6h358sh7.cloudfront.net/1003/1231231231.jpg",
    "originalImage": {
        "url": "https://dpbfm6h358sh7.cloudfront.net/1003/1231231231.jpg",
        "width": 123,
        "height": 456
    },
    "name": "Subfruit2",
    "url": "http://app.ecwid.com/store/4870020#!/Subfruit2/c/10861116",
    "productCount": 4,
    "enabledProductCount": 3,
    "description": "<p>arf34</p>",
    "enabled": true
}

Disabled category and public token request example

GET /api/v3/4870020/categories/10861117?token=public_123abcdaASasdASjndasAnsdu HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

Response

{
    "id": 10861117,
    "enabled": false
}

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

Category

FieldTypeDescription
idnumberInternal unique category ID
parentIdnumberID of the parent category, if any
orderBynumberSort order of the category in the parent category subcategories list
hdThumbnailUrlstringCategory HD thumbnail URL resized to fit 800x800px
thumbnailUrlstringCategory thumbnail URL. The thumbnail size is specified in the store settings. Resized to fit 400x400px by default
imageUrlstringCategory image URL. A resized original image to fit 1500x1500px
originalImageUrlstringLink to the original (not resized) category image
originalImage<ImageDetails>Details of the category image
namestringCategory name
urlstringURL of the category page in the store. Learn more
productCountnumberNumber of products in the category and its subcategories
enabledProductCountnumberNumber of enabled products in the category (excluding its subcategories)
descriptionstringThe category description in HTML
enabledbooleantrue if the category is enabled, false otherwise.
productIdsArray<number>IDs of products assigned to the category as they appear in Ecwid Control Panel > Catalog > Categories

ImageDetails

FieldTypeDescription
urlstringImage URL
widthintegerImage width
heightintegerImage height

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 StatusMeaningCode (optional)
400Request parameters are malformed
400The cleanUrls value is invalid. It must be either true or falseCLEAN_URLS_PARAMETER_IS_INVALID
404Category is not found
415Unsupported content-type: expected application/json or text/json
500Server 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 storefront URL field, where store owners can specify their storefront location. In case if it’s empty, Ecwid will use their starter 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 if a website supports the SEO-friendly (clean) URLs, you will need to use the cleanUrls request parameter in order to get URLs in that format.

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.

Add new category

Create a new category in an Ecwid store catalog.

Request

Request body

POST /api/v3/4870020/categories?token=alads043043lk0ds0 HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

{
    "name": "New Cool Category",
    "description": "Hey, this is my <b>new</b> category!",
    "enabled": true,
    "orderBy": 10,
    "parentId": 9691094
}

POST https://app.ecwid.com/api/v3/{storeId}/categories?token={token}

Query fieldTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Request body

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

Category

FieldTypeDescription
namestringCategory name
parentIdnumberID of the parent category. Omit this field to add root category
orderBynumberSort order of the category in the parent category subcategories list
descriptionstringThe category description in HTML
enabledbooleantrue to make category enabled, false otherwise. true is default
productIdsArray<number>IDs of the products to assign to the category

Response

Response example

{
    "id": 10869029
}

A JSON object of type 'CreateStatus’ with the following fields:

CreateStatus

FieldTypeDescription
idnumberID of the created category

Errors

Error response example

HTTP/1.1 404 Not Found
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 StatusMeaning
400Malformed request parameters
402The merchant plan category limit is reached
404The parent category or one of the assigned products is not found
409Data validation error: the category name or description exceed the max allowed length of characters
415Unsupported content-type: expected application/json or text/json
449Store catalog cannot be modified at the moment because import is in progress. Retry later
500Server error

Update category

Update an existing category in an Ecwid store referring to its ID.

Request

Request body

PUT /api/v3/4870020/categories/10869029?token=34534509340sdsreoiweurt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

{
  "name": "Updated name",
  "description": "Updated <b>description</b>",
  "productIds": [
    37208339,
    37208345
  ]
}

PUT https://app.ecwid.com/api/v3/{storeId}/categories/{categoryId}?token={token}

Query fieldTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
categoryIdnumberCategory internal ID

Request body

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

Category

FieldTypeDescription
namestringCategory name
parentIdnumberID of the parent category
orderBynumberSort order of the category in the parent category subcategories list
descriptionstringThe category description in HTML
enabledbooleantrue to make category enabled, false to disable it. true is default
productIdsArray<number>IDs of the products to assign to the category

Response

Response example

{
    "updateCount": 1
}

A JSON object of type 'UpdateStatus’ with the following fields:

UpdateStatus

FieldTypeDescription
updateCountnumberThe number of updated categories (1 or 0 depending on whether the update was successful)

Errors

Error response example

HTTP/1.1 404 Not Found
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 StatusMeaning
400Malformed request parameters
400Category name must not be empty
404The parent category or one of the assigned products is not found
409There was a conflict modifying the store (updating a category while it’s being edited elsewhere). Retry later.
415Unsupported content-type: expected application/json or text/json
449Store catalog cannot be modified at the moment because import is in progress. Retry later.
500Server error

Delete a category

Delete a category in an Ecwid store referring to its ID.

Request example

DELETE /api/v3/4870020/categories/10861116?token=abcdn339900932 HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/categories/{categoryId}?token={token}

Query fieldTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
categoryIdnumberCategory internal ID

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted categories (1 or 0 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 400 Bad request
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 StatusMeaning
400Malformed request parameters
415Unsupported content-type: expected application/json or text/json
449Store catalog cannot be modified at the moment because import is in progress. Retry later.
500Server error

Upload category image

Upload category image: if the category already has an image attached, the uploaded image will replace the existing one. Maximum allowed file size is 20Mb.

Request example

POST /api/v3/4870020/categories/1234657/image?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: image/jpeg
Cache-Control: no-cache

binary data

PHP Example

$file = file_get_contents('image.jpg');
$url = 'https://app.ecwid.com/api/v3/1003/categories/123456/image?token=abcdefg123456';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $file);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: image/jpeg;'));

$result = curl_exec($ch);
curl_close ($ch);

Python Example

import requests

request_url = "https://app.ecwid.com/api/v3/1003/categories/123456/image?token=abcdefg123456"

image_file_data = open('image.jpg', 'rb').read()

result = requests.post(request_url,data=image_file_data)

print(result.status_code)

POST https://app.ecwid.com/api/v3/{storeId}/categories/{categoryId}/image?token={token}&externalUrl={externalUrl}

NameTypeDescription
storeIdnumberEcwid store ID
categoryIdnumberCategory ID
tokenstringoAuth token
externalUrlstringExternal file URL available for public download. If specified, Ecwid will ignore any binary file data sent in a request

When uploading an image for a category, the image itself needs to be sent in the body of your request in a form of binary data. The file that you wish to upload needs to be prepared for that format and then sent to Ecwid API endpoint.

Alternatively, you can specify an externalURL to your file as a request parameter and Ecwid will download it from there.

Response

Response example

{
    "id": 240198557
}

A JSON object of type 'UploadStatus’ with the following fields:

UploadStatus

FieldTypeDescription
idnumberInternal image ID

Errors

Error response example

HTTP/1.1 422 Uploaded file cannot be processed. Please make sure you upload an image file

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
404Category is not found
413The image file is too large (Maximum allowed size is 20Mb)
415Unsupported content-type: expected application/octet-stream
422The uploaded file is not an image
500Uploading of the image file failed or there was an internal server error while processing a file. On of possible reasons is image

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Delete category image

Delete the category image from an Ecwid store.

Request example

DELETE /api/v3/4870020/categories/1234657/image?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/categories/{categoryId}/image?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
categoryIdnumberCategory ID
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted images (1 or 0 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
404Category is not found
500Deleting of the image file failed or there was an internal server error

Error response body (optional)

FieldTypeDescription
errorMessagestringError message