Categories

Category Index Endpoint

Structure

See View Category Endpoint for the structure of the category payload inside the data array.

Example Request

GET /api/categories?per_page=2

Example Response

{
    "current_page": 1,
    "data": [
        //...
    ],
    "first_page_url": "http://aero.test/api/categories?page=1",
    "from": 1,
    "last_page": 3,
    "last_page_url": "http://aero.test/api/categories?page=3",
    "next_page_url": "http://aero.test/api/categories?page=2",
    "path": "http://aero.test/api/categories",
    "per_page": 2,
    "prev_page_url": null,
    "to": 2,
    "total": 5
}

See View Category Endpoint for the structure of the category payload inside the data array.

View Category Endpoint

Structure

Category
Name
 Type
 Description
name string The name of the category
parent string The parent of the category
slug string The slug of the category, if not present it is auto-generated from name
reference string The reference of the category
logic string The logic of the rules for the category, and/or (defaults to or if not provided)
visible boolean The visibility of the category (defaults to true)
featured_image object The Image of the category
tags array An array of Tag objects
rules array An array of Listing Page Rule objects
content object The Listing Page Content of the category
options object The Listing Page Options of the category
seo object The SEO of the category
additional_attributes array An array of Additional Attribute objects
settings object A Settings object with grouped key-value pairs
Image
Name
 Type
 Description
url string The url of the image
Tag
Name
 Type
 Description
name string The name of the tag (e.g., Small or Red)
group object The tag group, see Tag Group
Tag Group
Name
 Type
 Description
name string The name of the tag group (e.g., Size or Colour)
Rule
Name
 Type
 Description
type string The type of the rule
requirement string The requirement of the rule
logic string The logic of the rule
data object The data for the rule, required keys vary based on type of the rule
data.tags array An array of Tag objects for a have_tags rule
data.manufacturers.*.id int The manufacturer id for a have_manufacturers rule
data.manufacturers.*.name string The manufacturer name for a have_manufacturers rule
data.price_list.id int The price list id for an in_price_list rule
data.price_list.name string The price list name for an in_price_list rule
data.category.id int The category id for an in_category rule
data.category.name string The category name for an in_category rule
data.days int The days for a published_within_days rule
data.start_at timestamp The start at date for a published_within rule
data.end_at timestamp The end at date for a published_within rule
data.min_price float The min price including tax, in whole units (e.g. pounds not pence) for price_between rule
data.max_price float The max price including tax, in whole units (e.g. pounds not pence) for price_between rule
data.currency string The currency code for price_between rule
Content
Name
 Type
 Description
summary string The summary content
description string The description content
small_image object The Small Image
medium_image object The Medium Image
large_image object The Large Image
Options
Name
 Type
 Description
categories.mode string The category filters mode (e.g., show_all/hide_all/show_some)
categories.values array The options for categories on the listings page
categories.values.*.id int The id of category
categories.values.*.name string The name of category
filters.mode int The facet filters mode (e.g., show_all/hide_all/show_some)
filters.values array The options for facet filters on the listings page
filters.values.*.name string The name of the facet filter, e.g. Manufacturer, Price, etc...
filters.values.*.collapsed boolean Whether to collapse the facet filter or not
sort_bys array An array of the applied sorts on the listings page (e.g., name-az, name-za, price-low, price-high, etc...)
per_page int The per page of the listings page
SEO
Name
 Type
 Description
heading string The SEO Heading
page_title string The SEO Page Title
meta_description string The SEO Meta Description
canonical string The SEO Canonical
noindex boolean The SEO No Index
nofollow boolean The SEO No Follow
Additional Attribute
Name
 Type
 Description
key string The key of the additional attribute
value string The value of the additional attribute
Settings

Settings are grouped as key-value pairs.

{
    "settings": {
        "_": {
            "no_group": "value"
        },
        "group": {
            "key": "value"
        }
    }
}

Example Request

GET /api/categories/{id|name|breadcrumb}

Example Response

{
    "id": 1,
    "name": "Mens",
    "parent": null,
    "reference": null,
    "slug": "mens",
    "featured_image": {
        "url": null
    },
    "content": {
        "summary": "",
        "description": "",
        "small_image": {
            "url": null
        },
        "medium_image": {
            "url": null
        },
        "large_image": {
            "url": null
        }
    },
    "tags": [],
    "rules": [],
    "options": {
        "categories": {
            "mode": "show_all",
            "values": []
        },
        "filters": {
            "mode": "show_all",
            "values": []
        },
        "sort_bys": [],
        "per_page": 24
    },
    "seo": {
        "heading": "",
        "page_title": "",
        "meta_description": "",
        "open_graph": "",
        "canonical": "",
        "noindex": null,
        "nofollow": null
    },
    "settings": [],
    "additional_attributes": []
}

Create Category Endpoint

Structure

Category
Name
 Type
 Description
 Required
id int The id for the category No
name string The name of the category Yes
parent string The parent of the category No
slug string The slug of the category, if not present it is auto-generated from name No
reference string The reference of the category No
logic string The logic of the rules for the category, and/or (defaults to or if not provided) No
visible boolean The visibility of the category (defaults to true) No
featured_image object The Image of the category No
tags array An array of Tag objects No
rules array An array of Listing Page Rule objects No
content object The Listing Page Content of the category No
options object The Listing Page Options of the category No
seo object The SEO of the category No
additional_attributes array An array of Additional Attribute objects No
settings object A Settings object with grouped key-value pairs No
Image
Name
 Type
 Description
 Required
src string The source url of the image Yes
Tag
Name
 Type
 Description
 Required
name string The name of the tag (e.g., Small or Red) Yes
group object The tag group, see Tag Group Yes
Tag Group
Name
 Type
 Description
 Required
name string The name of the tag group (e.g., Size or Colour) Yes
Rule
Name
 Type
 Description
 Required
type string Rule type. Allowed values: in_category, in_price_list, have_manufacturers, have_tags, price_between, reduced, published_within_days, published_within Yes
requirement string Requirement for the rule. Allowed values: must, must_not. Defaults to must No
logic string How this rule combines with others. Allowed values: and, or. Defaults to or No
data object Rule-specific data (see below). Keys vary depending on type Yes
data.tags array An array of Tag ids (or names formatted as group|name). Required if type = have_tags Conditional
data.manufacturers array An array of manufacturer ids (or names). Required if type = have_manufacturers Conditional
data.price_list string Price list id (or name). Required if type = in_price_list Conditional
data.category string Category id (or name/breadcrumb, e.g., Mens > Coats). Required if type = in_category Conditional
data.days int Number of days. Required if type = published_within_days Conditional
data.start_at timestamp The start date. Required if type = published_within Conditional
data.end_at timestamp The end date. Optional if type = published_within Conditional
data.min_price float Minimum price (including tax) in store’s default currency, whole units only (e.g. pounds, not pence). Required if type = price_between Conditional
data.max_price float Maximum price (including tax) in store’s default currency, whole units only. Required if type = price_between Conditional

 The rules are nested within arrays to achieve grouping, see rules in Example Request for clarity

Content
Name
 Type
 Description
 Required
summary string The summary content No
description string The description content No
small_image object The Small Image No
medium_image object The Medium Image No
large_image object The Large Image No
Options
Name
 Type
 Description
 Required
categories.mode string Categories filter display mode. Allowed values: show_all, hide_all, show_some. Default: show_all No
categories.values array An array of category ids (or names/breadcrumbs, e.g. Mens > Coats) to show. Required if categories.mode = show_some Conditional
filters.mode int Facet filters display mode. Allowed values: show_all, hide_all, show_some. Default: show_all No
filters.values array The options for facet filters on the listings page. Required if filters.mode = show_some Conditional
filters.values.*.name string The name of the facet filter, e.g. Category, Price, etc... Yes
filters.values.*.collapsed boolean Whether to collapse the facet filter or not Yes
sort_bys array An array of the applied sorts on the listings page (e.g., name-az, name-za, price-low, price-high, etc...) No
per_page int The per page of the listings page (defaults to 24) No
SEO
Name
 Type
 Description
 Required
heading string The SEO Heading No
page_title string The SEO Page Title No
meta_description string The SEO Meta Description No
canonical string The SEO Canonical No
noindex boolean The SEO No Index No
nofollow boolean The SEO No Follow No
Additional Attribute
Name
 Type
 Description
 Required
key string The key of the additional attribute Yes
value string The value of the additional attribute Yes
Settings

Settings are grouped as key-value pairs.

{
    "settings": {
        "_": {
            "no_group": "value"
        },
        "group": {
            "key": "value"
        }
    }
}

Example Request

POST /api/categories/
{
    "name": "Mens",
    "slug": "mens",
    "parent": 1,
    "visible": false,
    "content": {
        "summary": "Listing Page Summary Description",
        "description": "Listing Page Content Description"
    },
    "tags": [
        {
            "group": {
                "name": "Size"
            },
            "name": "Small"
        }
    ],
    "rules": [
        [
            {
                "type": "have_tags",
                "requirement": "must",
                "logic": "or",
                "data": {
                    "tags": [
                        1
                    ]
                }
            },
            {
                "type": "in_category",
                "requirement": "must",
                "logic": "and",
                "data": {
                    "category": 1
                }
            }
        ],
        [
            {
                "type": "in_price_list",
                "requirement": "must",
                "logic": "and",
                "data": {
                    "price_list": 1
                }
            }
        ],
        [
            {
                "type": "price_between",
                "requirement": "must",
                "logic": "and",
                "data": {
                    "min_price": 100,
                    "max_price": 200
                }
            },
            {
                "type": "reduced",
                "requirement": "must",
                "logic": "and"
            }
        ],
        [
            {
                "type": "published_within_days",
                "requirement": "must",
                "logic": "and",
                "data": {
                    "days": "12"
                }
            },
            {
                "type": "have_manufacturers",
                "requirement": "must",
                "logic": "and",
                "data": {
                    "manufacturers": [
                        1
                    ]
                }
            }
        ]
    ],
    "options": {
        "categories": {
            "mode": "show_some",
            "values": [
                1
            ]
        },
        "filters": {
            "mode": "show_some",
            "values": [
                {
                    "name": "Price",
                    "collapsed": true
                },
                {
                    "name": "Manufacturer"
                }
            ]
        },
        "sort_bys": [
            "model-az",
            "manufacturer-za"
        ],
        "per_page": 2
    },
    "seo": {
        "heading": "test heading",
        "page_title": "test page title",
        "meta_description": "test meta description",
        "noindex": 0,
        "nofollow": 0
    },
    "additional_attributes": [
        {
            "key": "test_name",
            "value": "test_value"
        }
    ]
}

Example Response

{
    "category": {
        "id": 1
    }
}

Update Category Endpoint

Structure

Category
Name
 Type
 Description
 Required
name string The name of the category No
parent string The parent of the category No
slug string The slug of the category, if not present it is auto-generated from name No
reference string The reference of the category No
logic string The logic of the rules for the category, and/or (defaults to or if not provided) No
visible boolean The visibility of the category (defaults to true) No
featured_image object The Image of the category No
tags array An array of Tag objects No
rules array An array of Listing Page Rule objects No
content object The Listing Page Content of the category No
options object The Listing Page Options of the category No
seo object The SEO of the category No
additional_attributes array An array of Additional Attribute objects No
settings object A Settings object with grouped key-value pairs No
Image
Name
 Type
 Description
 Required
src string The source url of the image Yes
Tag
Name
 Type
 Description
 Required
name string The name of the tag (e.g., Small or Red) Yes
group object The tag group, see Tag Group Yes
Tag Group
Name
 Type
 Description
 Required
name string The name of the tag group (e.g., Size or Colour) Yes
Rule
Name
 Type
 Description
 Required
type string Rule type. Allowed values: in_category, in_price_list, have_manufacturers, have_tags, price_between, reduced, published_within_days, published_within Yes
requirement string Requirement for the rule. Allowed values: must, must_not. Defaults to must No
logic string How this rule combines with others. Allowed values: and, or. Defaults to or No
data object Rule-specific data (see below). Keys vary depending on type Yes
data.tags array An array of Tag ids (or names formatted as group|name). Required if type = have_tags Conditional
data.manufacturers array An array of manufacturer ids (or names). Required if type = have_manufacturers Conditional
data.price_list string Price list id (or name). Required if type = in_price_list Conditional
data.category string Category id (or name/breadcrumb, e.g., Mens > Coats). Required if type = in_category Conditional
data.days int Number of days. Required if type = published_within_days Conditional
data.start_at timestamp The start date. Required if type = published_within Conditional
data.end_at timestamp The end date. Optional if type = published_within Conditional
data.min_price float Minimum price (including tax) in store’s default currency, whole units only (e.g. pounds, not pence). Required if type = price_between Conditional
data.max_price float Maximum price (including tax) in store’s default currency, whole units only. Required if type = price_between Conditional

 The rules are nested within arrays to achieve grouping, see rules in Example Request for clarity

Content
Name
 Type
 Description
 Required
summary string The summary content No
description string The description content No
small_image object The Small Image No
medium_image object The Medium Image No
large_image object The Large Image No
Options
Name
 Type
 Description
 Required
categories.mode string Categories filter display mode. Allowed values: show_all, hide_all, show_some. Default: show_all No
categories.values array An array of category ids (or names/breadcrumbs, e.g. Mens > Coats) to show. Required if categories.mode = show_some Conditional
filters.mode int Facet filters display mode. Allowed values: show_all, hide_all, show_some. Default: show_all No
filters.values array The options for facet filters on the listings page. Required if filters.mode = show_some Conditional
filters.values.*.name string The name of the facet filter, e.g. Category, Price, etc... Yes
filters.values.*.collapsed boolean Whether to collapse the facet filter or not Yes
sort_bys array An array of the applied sorts on the listings page (e.g., name-az, name-za, price-low, price-high, etc...) No
per_page int The per page of the listings page (defaults to 24) No
SEO
Name
 Type
 Description
 Required
heading string The SEO Heading No
page_title string The SEO Page Title No
meta_description string The SEO Meta Description No
canonical string The SEO Canonical No
noindex boolean The SEO No Index No
nofollow boolean The SEO No Follow No
Additional Attribute
Name
 Type
 Description
 Required
key string The key of the additional attribute Yes
value string The value of the additional attribute Yes
Settings

Settings are grouped as key-value pairs.

{
    "settings": {
        "_": {
            "no_group": "value"
        },
        "group": {
            "key": "value"
        }
    }
}

Example Request

PUT /api/categories/{id|name|breadcrumb}
{
    "name": "Updated Mens",
    "slug": "mens-mens",
    "content": {
        "description": "Updated Mens"
    },
    "seo": {
        "heading": "Updated Mens"
    },
    "tags": [
        {
            "name": "Green",
            "group": {
                "name": "Colour"
            }
        }
    ]
}

Example Response

{
    "category": {
        "id": 1
    }
}

Delete Category Endpoint

Example Request

DELETE /api/categories/{id|name|breadcrumb}

Example Response

204 No Content