1. Помощен център
  2. Documentation API
  3. Categories API

Categories API

Use the categories API to extract information about categories, to add new categories or to update the data of existing categories.

Fields available

Extract list of categories

Extract category data

Add a category

Modify category data

Delete a category

Fields available

The list below indicates all the fields available for this API, which are returned when you extract an individual list or resource, which can be modified, which are mandatory when creating a new resource or updating an existing resource.

Field Type Description List Not required
id in The category id ✔
name string The name of the category ✔ ✔
description string Category description ✔ ✔
meta_title string Meta category title ✔ ✔
meta_description string Category meta description ✔ ✔
parent_id int The id of the parent category ✔ ✔
page_template string The type of templates used for display in the case of categories that contain subcategories (products, subcategories, mixed, highlights) ✔ ✔
meta_fields object Additional fields ✔ ✔
url string Category URL ✔
meta_links object Category URLs for active languages
subcategories array List of subcategory ids
date_created date Category addition date (ISO 8601 format) ✔
status string Registration status (active, inactive) ✔ ✔

TIP
Any field returned that is not documented can be ignored because it is not yet available.

Extract list of categories

Shows the filtered list of records.

Type : Resource list
Method : GET
Url : /api/v2/categories
Filter results : Yes Field
Field selection : Yes
Include additional fields : Yes
Pagination : Yes

The http response code is 200 in case of success, the response will have the form of a list of resources related to the defined filters.

Only the list type fields will be included in the standard result. You can include additional fields that are not included by default using the parameter include and explicitly mentioning only the additional fields (separated by commas) that you want included.

GET /api/v2/categories?include=subcategories

You can filter the fields you want included in the result for each resource using the parameter fields and explicitly mentioning only the fields (separated by commas) you want included (the field id will always be included by default).

GET /api/v2/categories?fields=id,name,parent_id

Filter results

It is possible to filter the results by appending some specific parameters in the URL.

Parameter Description Example
id The category id id=101
ids Comma separated list of category ids ids=101,102,103
parent_id The id of the parent category parent_id=101
meta_fields Additional fields meta_fields[field_key]=field_value
created_after Date from which records were created (ISO 8601 format) created_after=2019-01-01
created_before Date up to which records were created (ISO 8601 format) created_before=2020-01-01
status Registration status (active, inactive) status=active 
GET /api/v2/categories?parent_id=0&status=active

Sort results

It is possible to sort the results by appending some specific parameters in the URL.

Parameter Description Example
name Ascending category name sort=name
name.desc Descending category name sort=name.desc
date_created Date of creation, ascending order sort=date_created
date_created.desc Date of creation, descending order sort=date_created.desc
user_defined Depending on the custom order set at the Cpanel level sort=user_defined 
GET /api/v2/categories?sort=name

Pagination

Pagination parameters can be added to the API request to limit the number of entries per page and access all available pages.

Parameter Type Default
start int 0
limit int 100

The maximum number of records per page cannot exceed 100.

GET /api/v2/categories?start=100&limit=100

Format request

Example of a CURL request that extracts all records:

curl --request GET \
--url 'https://shop.demo.ro/api/v2/categories' \
--header 'Accept: application/json' \
--header 'Content-type: application/json' \
--header 'Authorization: Basic {base64-encoded-credentials}'

Extract all records, extract all fields

Request example

GET /api/v2/categories
Response example 

{
  "data": [
    {
      "id": 101,
      "name": "Men",
      "description": "Best online clothing shops for men",
      "status": "active",
      "parent_id": 0,
      "meta_title": null,
      "meta_description": null,
      "date_created": "2020-01-01T01:01:01+02:00",
      "page_template": "subcategories"
    },
    {
      "id": 102,
      "name": "Women",
      "description": "Women clothing in all styles and sizes",
      "status": "active",
      "parent_id": 0,
      "meta_title": null,
      "meta_description": null,
      "date_created": "2020-01-01T01:01:01+02:00",
      "page_template": "subcategories"
    },
    {
      "id": 103,
      "name": "Accessories",
      "description": "Find a wide selection of accessories for men & women",
      "status": "active",
      "parent_id": 0,
      "meta_title": null,
      "meta_description": null,
      "date_created": "2020-01-01T01:01:01+02:00",
      "page_template": "subcategories"
    },    
    {
      "id": 1011,
      "name": "Pants",
      "description": "Explore the new collection of men pants",
      "status": "active",
      "parent_id": 101,
      "meta_title": null,
      "meta_description": null,
      "date_created": "2020-01-01T01:01:01+02:00"
    },
    {
      "id": 1012,
      "name": "Shirts",
      "description": "Discover our stylish men's shirts",
      "status": "active",
      "parent_id": 101,
      "meta_title": null,
      "meta_description": null,
      "date_created": "2020-01-01T01:01:01+02:00"
    },
    {
      "id": 1013,
      "name": "Shoes",
      "description": "The most stylish and comfortable men's shoes",
      "status": "active",
      "parent_id": 101,
      "meta_title": null,
      "meta_description": null,
      "date_created": "2020-01-01T01:01:01+02:00"
    },
    { ... },
  ],
  "meta": {
    "count": {
      "total": 50,
      "current": 50,
      "start": 0,
      "limit": 100
    },
    "links": {
      "prev": null,
      "current": "/api/v2/categories",
      "next": null
    }
  }
}

Extract all records, filter only certain fields

Request example

GET /api/v2/categories?fields=id,name,parent_id
Response example 

{
  "data": [
    {
      "id": 101,
      "name": "Men",
      "parent_id": 0
    },
    {
      "id": 102,
      "name": "Women",
      "parent_id": 0
    },
    {
      "id": 103,
      "name": "Accessories",
      "parent_id": 0
    },    
    {
      "id": 1011,
      "name": "Pants",
      "parent_id": 101
    },
     {
      "id": 1012,
      "name": "Shirts",
      "parent_id": 101
    },
    {
      "id": 1013,
      "name": "Shoes",
      "parent_id": 101
    },
    { ... },
  ],
  "meta": {
    "count": {
      "total": 50,
      "current": 50,
      "start": 0,
      "limit": 100
    },
    "links": {
      "prev": null,
      "current": "/api/v2/categories",
      "next": null
    }
  }
}

Extract all records, include additional fields

Request example

GET /api/v2/categories?include=url
Response example 

{
  "data": [
    {
      "id": 101,
      "name": "Men",
      "description": "Best online clothing shops for men",
      "status": "active",
      "parent_id": 0,
      "meta_title": null,
      "meta_description": null,
      "date_created": "2020-01-01T01:01:01+02:00",
      "url": "https://shop.demo.ro/men",
      "page_template": "subcategories"
    },
    {
      "id": 102,
      "name": "Women",
      "description": "Women clothing in all styles and sizes",
      "status": "active",
      "parent_id": 0,
      "meta_title": null,
      "meta_description": null,
      "date_created": "2020-01-01T01:01:01+02:00",
      "url": "https://shop.demo.ro/women",
      "page_template": "subcategories"
    },
    {
      "id": 103,
      "name": "Accessories",
      "description": "Find a wide selection of accessories for men & women",
      "status": "active",
      "parent_id": 0,
      "meta_title": null,
      "meta_description": null,
      "date_created": "2020-01-01T01:01:01+02:00",
      "url": "https://shop.demo.ro/accessories",
      "page_template": "subcategories"
    },    
    {
      "id": 1011,
      "name": "Pants",
      "description": "Explore the new collection of men pants",
      "status": "active",
      "parent_id": 101,
      "meta_title": null,
      "meta_description": null,
      "date_created": "2020-01-01T01:01:01+02:00",
      "url": "https://shop.demo.ro/men-pants"
    },
    {
      "id": 1012,
      "name": "Shirts",
      "description": "Discover our stylish men's shirts",
      "status": "active",
      "parent_id": 101,
      "meta_title": null,
      "meta_description": null,
      "date_created": "2020-01-01T01:01:01+02:00",
      "url": "https://shop.demo.ro/men-shirts"
    },
    {
      "id": 1013,
      "name": "Shoes",
      "description": "The most stylish and comfortable men's shoes",
      "status": "active",
      "parent_id": 101,
      "meta_title": null,
      "meta_description": null,
      "date_created": "2020-01-01T01:01:01+02:00",
      "url": "https://shop.demo.ro/men-shoes"
    },
    { ... },
  ],
  "meta": {
    "count": {
      "total": 50,
      "current": 50,
      "start": 0,
      "limit": 100
    },
    "links": {
      "prev": null,
      "current": "/api/v2/categories",
      "next": null
    }
  }
}

Filter the records based on the list of IDs, filter only certain fields

Request example

GET /api/v2/categories?ids=101,102&fields=id,name
Resonse example 

{
  "data": [
    {
      "id": 101,
      "name": "Men"
    },
    {
      "id": 102,
      "name": "Women"
    }
  ],
  "meta": {
    "count": {
      "total": 2,
      "current": 2,
      "start": 0,
      "limit": 100
    },
    "links": {
      "prev": null,
      "current": "/api/v2/categories",
      "next": null
    }
  }
}

Extract category data

It displays the data of a single record.

Type : Individual resource
Method : GET
Url : /api/v2/categories/{id}
Filter results : No
Field selection : Yes
Inclusion of additional fields : No
Pagination : No

The http response code is 200 in case of success, the response will have the form of an individual resource related to the requested id.

You can filter the fields you want included in the result for each resource using the parameter fields and explicitly mentioning only the fields (separated by commas) you want included (the id field will always be included by default).

GET /api/v2/categories/{id}?fields=id,name,parent_id

Format request

Example of a CURL request that returns an individual record:

curl --request GET \
--url 'https://shop.demo.ro/api/v2/categories/101' \
--header 'Accept: application/json' \
--header 'Content-type: application/json' \
--header 'Authorization: Basic {base64-encoded-credentials}'

Extract all fields

Request example

GET /api/v2/categories/101
Response example 

{
  "id": 101,
  "name": "Men",
  "description": "Best online clothing shops for men",
  "status": "active",
  "parent_id": 0,
  "meta_title": null,
  "meta_description": null,
  "date_created": "2020-01-01T01:01:01+02:00",
  "meta_fields": {
    "homepage_display": "on"
  },
  "subcategories": [
    1011,
    1012,
    1013
  ],
  "url": "https://shop.demo.ro/men",
  "meta_links": {
    "en_US": {
      "lang": "en_US",
      "url": "https://shop.demo.ro/en/men"
    }
  },
  "page_template": "subcategories"
}

Filter only certain fields

Request example

GET /api/v2/categories/101?fields=id,name,subcategories
Response example 

{
  "id": 101,
  "name": "Men",
  "subcategories": [
    1011,
    1012,
    1013
  ]
}

Add a category

Allows adding a new record.

Type : Create resource
Method : POST
Url :/api/v2/categories

The response http code is 200in case of success, the response will have the form of an individual resource representing the record that was just added.

Format request

Example of a CURL request that creates a new record:

curl --request POST \
--url 'https://shop.demo.ro/api/v2/categories' \
--header 'Accept: application/json' \
--header 'Content-type: application/json' \
--header 'Authorization: Basic {base64-encoded-credentials}' \
--data-raw '{
  "name": "Women",
  "description": "Women clothing in all styles and sizes",
  "parent_id": 102
}'

Add root category

Request example

POST /api/v2/categories
{
  "name": "Women",
  "description": "Women clothing in all styles and sizes",
  "parent_id": 0  
}
Response example 

{
  "id": 102,
  "name": "Women",
  "description": "Women clothing in all styles and sizes",
  "status": "active",
  "parent_id": 0,
  "meta_title": null,
  "meta_description": null,
  "date_created": "2020-01-01T01:01:01+02:00",
  "meta_fields": null,
  "subcategories": null,
  "url": "https://shop.demo.ro/women",
  "meta_links": {
    "en_US": {
      "lang": "en_US",
      "url": "https://shop.demo.ro/en/women"
    }
  }
}

Add subcategory and additional fields

Request example

POST /api/v2/categories
{
  "name": "Pants",
  "description": "Explore the new collection of men pants",
  "status": "active",
  "parent_id": 101,
  "meta_fields": {
    "homepage_display": "on"
  }
}
Response example 

{
  "id": 1011,
  "name": "Pants",
  "description": "Explore the new collection of men pants",
  "status": "active",
  "parent_id": 101,
  "meta_title": null,
  "meta_description": null,
  "date_created": "2020-01-01T01:01:01+02:00",
  "meta_fields": {
    "homepage_display": "on"
  },
  "subcategories": null,
  "url": "https://shop.demo.ro/men-pants",
  "meta_links": {
    "en_US": {
      "lang": "en_US",
      "url": "https://shop.demo.ro/en/men-pants"
    }
  }
}

Change categories

Allows updating an existing record based on ID.

Type : Resource update
Verb : PATCH
Url :/api/v2/categories/{id}

The response http code is 200in case of success, the response will take the form of an individual resource representing the record that has just been updated.

Format request

Example of a CURL request that updates an existing record:

curl --request PATCH \
--url 'https://shop.demo.ro/api/v2/categories/101' \
--header 'Accept: application/json' \
--header 'Content-type: application/json' \
--header 'Authorization: Basic {base64-encoded-credentials}' \
--data-raw '{
  "description": "Best online clothing shops for men",
  "meta_title": "Men Clothing & Shoes"
}'

Update category data

Request example

PATCH /api/v2/categories/101
{
  "meta_title": "Men Clothing & Shoes",
  "meta_fields": {
    "homepage_display": "off"
  },
}
Response example 

{
  "id": 101,
  "name": "Men",
  "description": "Best online clothing shops for men",
  "status": "active",
  "parent_id": 0,
  "meta_title": "Men Clothing & Shoes",
  "meta_description": null,
  "date_created": "2020-01-01T01:01:01+02:00",
  "meta_fields": {
    "homepage_display": "off"
  },
  "subcategories": [
    1011,
    1012,
    1013
  ],
  "url": "https://shop.demo.ro/men",
  "meta_links": {
    "en_US": {
      "lang": "en_US",
      "url": "https://shop.demo.ro/en/men"
    }
  },
  "page_template": "subcategories"
}

Category status change

Request example

PATCH /api/v2/categories/101
{
  "status": "inactive"
}
Response example 

{
  "id": 101,
  "name": "Men",
  "description": "Best online clothing shops for men",
  "status": "inactive",
  "parent_id": 0,
  "meta_title": null,
  "meta_description": null,
  "date_created": "2020-01-01T01:01:01+02:00",
  "meta_fields": {
    "homepage_display": "on"
  },
  "subcategories": [
    1011,
    1012,
    1013
  ],
  "url": "https://shop.demo.ro/men",
  "meta_links": {
    "en_US": {
      "lang": "en_US",
      "url": "https://shop.demo.ro/en/men"
    }
  },
  "page_template": "subcategories"
}

Delete a category

Allows the deletion of an existing record based on ID. This implies the deletion of all additional information.

Type : Delete resource
Method : DELETE
Url :/api/v2/categories/{id}

The http response code is 200 in case of success.

Format request

Example of a CURL request that deletes an existing record:

curl --request DELETE \
--url 'https://shop.demo.ro/api/v2/categories/101' \
--header 'Accept: application/json' \
--header 'Content-type: application/json' \
--header 'Authorization: Basic {base64-encoded-credentials}'

Request example

DELETE /api/v2/categories/101
Response example 

{
  "ok": true
}
Последна промяна: 11 Aug 2022
Полезна ли бе страницата?
Все още ли имате нужда от помощ?