# Categories

# Category Index Endpoint

#### Structure

See [View Category Endpoint](https://support.aerocommerce.com/books/api/page/view-category-endpoint) for the structure of the category payload inside the `data` array.

#### Example Request

```
GET /api/categories?per_page=2
```

#### Example Response

```json
{
    "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
}
```

<p class="callout info">See [View Category Endpoint](https://support.aerocommerce.com/books/api/page/view-category-endpoint) for the structure of the category payload inside the `data` array.</p>

# View Category Endpoint

#### Structure

##### Category

<table border="1" id="bkmrk-name-type-descriptio-5" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`name`</td><td>string</td><td>The name of the category</td></tr><tr><td>`parent`</td><td>string</td><td>The parent of the category</td></tr><tr><td>`slug`</td><td>string</td><td>The slug of the category, if not present it is auto-generated from name</td></tr><tr><td>`reference`</td><td>string</td><td>The reference of the category</td></tr><tr><td>`logic`</td><td>string</td><td>The logic of the rules for the category, and/or (defaults to or if not provided)</td></tr><tr><td>`visible`</td><td>boolean</td><td>The visibility of the category (defaults to `true`)</td></tr><tr><td>`featured_image`</td><td>object</td><td>The [Image](https://support.aerocommerce.com/books/api/page/view-category-endpoint#bkmrk-image) of the category</td></tr><tr><td>`tags`</td><td>array</td><td>An array of [Tag](https://support.aerocommerce.com/books/api/page/view-category-endpoint#bkmrk-tag) objects</td></tr><tr><td>`rules`</td><td>array</td><td>An array of Listing Page [Rule](https://support.aerocommerce.com/books/api/page/view-category-endpoint#bkmrk-rule) objects</td></tr><tr><td>`content`</td><td>object</td><td>The Listing Page [Content](https://support.aerocommerce.com/books/api/page/view-category-endpoint#bkmrk-content) of the category</td></tr><tr><td>`options`</td><td>object</td><td>The Listing Page [Options](https://support.aerocommerce.com/books/api/page/view-category-endpoint#bkmrk-options) of the category</td></tr><tr><td>`seo`</td><td>object</td><td>The [SEO](https://support.aerocommerce.com/books/api/page/view-category-endpoint#bkmrk-seo) of the category</td></tr><tr><td>`additional_attributes`</td><td>array</td><td>An array of [Additional Attribute](https://support.aerocommerce.com/books/api/page/view-category-endpoint#bkmrk-additional-attribute) objects</td></tr><tr><td>`settings`</td><td>object</td><td>A [Settings](https://support.aerocommerce.com/books/api/page/view-category-endpoint#bkmrk-settings) object with grouped key-value pairs</td></tr></tbody></table>

##### Image

<table border="1" id="bkmrk-name-type-descriptio" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`url`</td><td>string</td><td>The url of the image</td></tr></tbody></table>

##### Tag

<table border="1" id="bkmrk-name-type-descriptio-1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`name`</td><td>string</td><td>The name of the tag (e.g., Small or Red)</td></tr><tr><td>`group`</td><td>object</td><td>The tag group, see [Tag Group](https://support.aerocommerce.com/books/api/page/view-category-endpoint#bkmrk-tag-group)</td></tr></tbody></table>

##### Tag Group

<table border="1" id="bkmrk-name-type-descriptio-2" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`name`</td><td>string</td><td>The name of the tag group (e.g., Size or Colour)</td></tr></tbody></table>

##### Rule

<table border="1" id="bkmrk-name-type-descriptio-3" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`type`</td><td>string</td><td>The type of the rule</td></tr><tr><td>`requirement`</td><td>string</td><td>The requirement of the rule</td></tr><tr><td>`logic`</td><td>string</td><td>The logic of the rule</td></tr><tr><td>`data`</td><td>object</td><td>The data for the rule, required keys vary based on `type` of the rule</td></tr><tr><td>`data.tags`</td><td>array</td><td>An array of [Tag](https://support.aerocommerce.com/books/api/page/view-category-endpoint#bkmrk-tag) objects for a `have_tags` rule</td></tr><tr><td>`data.manufacturers.*.id`</td><td>int</td><td>The manufacturer id for a `have_manufacturers` rule</td></tr><tr><td>`data.manufacturers.*.name`</td><td>string</td><td>The manufacturer name for a `have_manufacturers` rule</td></tr><tr><td>`data.price_list.id`</td><td>int</td><td>The price list id for an `in_price_list` rule</td></tr><tr><td>`data.price_list.name`</td><td>string</td><td>The price list name for an `in_price_list` rule</td></tr><tr><td>`data.category.id`</td><td>int</td><td>The category id for an `in_category` rule</td></tr><tr><td>`data.category.name`</td><td>string</td><td>The category name for an `in_category` rule</td></tr><tr><td>`data.days`</td><td>int</td><td>The days for a `published_within_days` rule</td></tr><tr><td>`data.start_at`</td><td>timestamp</td><td>The start at date for a `published_within` rule</td></tr><tr><td>`data.end_at`</td><td>timestamp</td><td>The end at date for a `published_within` rule</td></tr><tr><td>`data.min_price`</td><td>float</td><td>The min price **including tax**, in whole units (e.g. pounds not pence) for `price_between` rule</td></tr><tr><td>`data.max_price`</td><td>float</td><td>The max price **including tax**, in whole units (e.g. pounds not pence) for `price_between` rule</td></tr><tr><td>`data.currency`</td><td>string</td><td>The currency code for `price_between` rule</td></tr></tbody></table>

##### Content

<table border="1" id="bkmrk-name-type-descriptio-6" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`summary`</td><td>string</td><td>The summary content</td></tr><tr><td>`description`</td><td>string</td><td>The description content</td></tr><tr><td>`small_image`</td><td>object</td><td>The Small Image</td></tr><tr><td>`medium_image`</td><td>object</td><td>The Medium Image</td></tr><tr><td>`large_image`</td><td>object</td><td>The Large Image</td></tr></tbody></table>

##### Options

<table border="1" id="bkmrk-name-type-descriptio-7" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`categories.mode`</td><td>string</td><td>The category filters mode (e.g., show\_all/hide\_all/show\_some)</td></tr><tr><td>`categories.values`</td><td>array</td><td>The options for categories on the listings page</td></tr><tr><td>`categories.values.*.id`</td><td>int</td><td>The id of category</td></tr><tr><td>`categories.values.*.name`</td><td>string</td><td>The name of category</td></tr><tr><td>`filters.mode`</td><td>int</td><td>The facet filters mode (e.g., show\_all/hide\_all/show\_some)</td></tr><tr><td>`filters.values`</td><td>array</td><td>The options for facet filters on the listings page</td></tr><tr><td>`filters.values.*.name`</td><td>string</td><td>The name of the facet filter, e.g. Manufacturer, Price, etc...</td></tr><tr><td>`filters.values.*.collapsed`</td><td>boolean</td><td>Whether to collapse the facet filter or not</td></tr><tr><td>`sort_bys`</td><td>array</td><td>An array of the applied sorts on the listings page (e.g., name-az, name-za, price-low, price-high, etc...)</td></tr><tr><td>`per_page`</td><td>int</td><td>The per page of the listings page</td></tr></tbody></table>

##### SEO

<table border="1" id="bkmrk-name-type-descriptio-8" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`heading`</td><td>string</td><td>The SEO Heading</td></tr><tr><td>`page_title`</td><td>string</td><td>The SEO Page Title</td></tr><tr><td>`meta_description`</td><td>string</td><td>The SEO Meta Description</td></tr><tr><td>`canonical`</td><td>string</td><td>The SEO Canonical</td></tr><tr><td>`noindex`</td><td>boolean</td><td>The SEO No Index</td></tr><tr><td>`nofollow`</td><td>boolean</td><td>The SEO No Follow</td></tr></tbody></table>

##### Additional Attribute

<table border="1" id="bkmrk-name-type-descriptio-9" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`key`</td><td>string</td><td>The key of the additional attribute</td></tr><tr><td>`value`</td><td>string</td><td>The value of the additional attribute</td></tr></tbody></table>

##### Settings

Settings are grouped as key-value pairs.

- Use "\_" for ungrouped settings.
- Each group contains its own object of key-value pairs.

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

#### Example Request

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

#### Example Response

```json
{
    "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

<table border="1" id="bkmrk-name-type-descriptio" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`id`</td><td>int</td><td>The id for the category</td><td>No</td></tr><tr><td>`name`</td><td>string</td><td>The name of the category</td><td>Yes</td></tr><tr><td>`parent`</td><td>string</td><td>The parent of the category</td><td>No</td></tr><tr><td>`slug`</td><td>string</td><td>The slug of the category, if not present it is auto-generated from name</td><td>No</td></tr><tr><td>`reference`</td><td>string</td><td>The reference of the category</td><td>No</td></tr><tr><td>`logic`</td><td>string</td><td>The logic of the rules for the category, and/or (defaults to or if not provided)</td><td>No</td></tr><tr><td>`visible`</td><td>boolean</td><td>The visibility of the category (defaults to `true`)</td><td>No</td></tr><tr><td>`featured_image`</td><td>object</td><td>The Image of the category</td><td>No</td></tr><tr><td>`tags`</td><td>array</td><td>An array of [Tag](https://support.aerocommerce.com/books/api/page/create-category-endpoint#bkmrk-tag) objects</td><td>No</td></tr><tr><td>`rules`</td><td>array</td><td>An array of Listing Page [Rule](https://support.aerocommerce.com/books/api/page/create-category-endpoint#bkmrk-rule) objects</td><td>No</td></tr><tr><td>`content`</td><td>object</td><td>The Listing Page [Content](https://support.aerocommerce.com/books/api/page/create-category-endpoint#bkmrk-content) of the category</td><td>No</td></tr><tr><td>`options`</td><td>object</td><td>The Listing Page [Options](https://support.aerocommerce.com/books/api/page/create-category-endpoint#bkmrk-options) of the category</td><td>No</td></tr><tr><td>`seo`</td><td>object</td><td>The [SEO](https://support.aerocommerce.com/books/api/page/create-category-endpoint#bkmrk-seo) of the category</td><td>No</td></tr><tr><td>`additional_attributes`</td><td>array</td><td>An array of [Additional Attribute](https://support.aerocommerce.com/books/api/page/create-category-endpoint#bkmrk-additional-attribute) objects</td><td>No</td></tr><tr><td>`settings`</td><td>object</td><td>A [Settings](https://support.aerocommerce.com/books/api/page/create-category-endpoint#bkmrk-settings) object with grouped key-value pairs</td><td>No</td></tr></tbody></table>

##### Image

<table border="1" id="bkmrk-name-type-descriptio-1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`src`</td><td>string</td><td>The source url of the image</td><td>Yes</td></tr></tbody></table>

##### Tag

<table border="1" id="bkmrk-name-type-descriptio-2" style="border-collapse: collapse; width: 100%; height: 111.789px;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Name**  
</td><td style="height: 29.7969px;">**Type**  
</td><td style="height: 29.7969px;">**Description**  
</td><td style="height: 29.7969px;">**Required**  
</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`name`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The name of the tag (e.g., Small or Red)</td><td style="height: 46.5938px;">Yes</td></tr><tr style="height: 35.3984px;"><td style="height: 35.3984px;">`group`</td><td style="height: 35.3984px;">object</td><td style="height: 35.3984px;">The tag group, see [Tag Group](https://support.aerocommerce.com/books/api/page/create-category-endpoint#bkmrk-tag-group)</td><td style="height: 35.3984px;">Yes</td></tr></tbody></table>

##### Tag Group

<table border="1" id="bkmrk-name-type-descriptio-3" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`name`</td><td>string</td><td>The name of the tag group (e.g., Size or Colour)</td><td>Yes</td></tr></tbody></table>

##### Rule

<table border="1" id="bkmrk-name-type-descriptio-4" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`type`</td><td>string</td><td>Rule type. Allowed values: `in_category`, `in_price_list`, `have_manufacturers`, `have_tags`, `price_between`, `reduced`, `published_within_days`, `published_within`</td><td>Yes</td></tr><tr><td>`requirement`</td><td>string</td><td>Requirement for the rule. Allowed values: `must`, `must_not`. Defaults to `must`</td><td>No</td></tr><tr><td>`logic`</td><td>string</td><td>How this rule combines with others. Allowed values: `and`, `or`. Defaults to `or`</td><td>No</td></tr><tr><td>`data`</td><td>object</td><td>Rule-specific data (see below). Keys vary depending on type</td><td>Yes</td></tr><tr><td>`data.tags`</td><td>array</td><td>An array of Tag ids (or names formatted as group|name). Required if `type = have_tags`</td><td>Conditional</td></tr><tr><td>`data.manufacturers`</td><td>array</td><td>An array of manufacturer ids (or names). Required if `type = have_manufacturers`</td><td>Conditional</td></tr><tr><td>`data.price_list`</td><td>string</td><td>Price list id (or name). Required if `type = in_price_list`</td><td>Conditional</td></tr><tr><td>`data.category`</td><td>string</td><td>Category id (or name/breadcrumb, e.g., Mens &gt; Coats). Required if `type = in_category`</td><td>Conditional</td></tr><tr><td>`data.days`</td><td>int</td><td>Number of days. Required if `type = published_within_days`</td><td>Conditional</td></tr><tr><td>`data.start_at`</td><td>timestamp</td><td>The start date. Required if `type = published_within`</td><td>Conditional</td></tr><tr><td>`data.end_at`</td><td>timestamp</td><td>The end date. Optional if `type = published_within`</td><td>Conditional</td></tr><tr><td>`data.min_price`</td><td>float</td><td>Minimum price (including tax) in store’s default currency, whole units only (e.g. pounds, not pence). Required if `type = price_between`</td><td>Conditional</td></tr><tr><td>`data.max_price`</td><td>float</td><td>Maximum price (including tax) in store’s default currency, whole units only. Required if `type = price_between`</td><td>Conditional</td></tr></tbody></table>

<p class="callout info"> The `rules` are nested within arrays to achieve grouping, see `rules` in Example Request for clarity</p>

##### Content

<table border="1" id="bkmrk-name-type-descriptio-5" style="border-collapse: collapse; width: 100%; height: 184.375px;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Name**  
</td><td style="height: 29.7969px;">**Type**  
</td><td style="height: 29.7969px;">**Description**  
</td><td style="height: 29.7969px;">**Required**  
</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">`summary`</td><td style="height: 29.7969px;">string</td><td style="height: 29.7969px;">The summary content</td><td style="height: 29.7969px;">No</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">`description`</td><td style="height: 29.7969px;">string</td><td style="height: 29.7969px;">The description content</td><td style="height: 29.7969px;">No</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">`small_image`</td><td style="height: 29.7969px;">object</td><td style="height: 29.7969px;">The Small [Image](https://support.aerocommerce.com/books/api/page/create-category-endpoint#bkmrk-image)</td><td style="height: 29.7969px;">No</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">`medium_image`</td><td style="height: 29.7969px;">object</td><td style="height: 29.7969px;">The Medium [Image](https://support.aerocommerce.com/books/api/page/create-category-endpoint#bkmrk-image)</td><td style="height: 29.7969px;">No</td></tr><tr style="height: 35.3906px;"><td style="height: 35.3906px;">`large_image`</td><td style="height: 35.3906px;">object</td><td style="height: 35.3906px;">The Large [Image](https://support.aerocommerce.com/books/api/page/create-category-endpoint#bkmrk-image)</td><td style="height: 35.3906px;">No</td></tr></tbody></table>

##### Options

<table border="1" id="bkmrk-name-type-descriptio-6" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`categories.mode`</td><td>string</td><td>Categories filter display mode. Allowed values: `show_all`, `hide_all`, `show_some`. Default: `show_all`</td><td>No</td></tr><tr><td>`categories.values`</td><td>array</td><td>An array of category ids (or names/breadcrumbs, e.g. Mens &gt; Coats) to show. Required if `categories.mode = show_some`</td><td>Conditional</td></tr><tr><td>`filters.mode`</td><td>int</td><td>Facet filters display mode. Allowed values: `show_all`, `hide_all`, `show_some`. Default: `show_all`</td><td>No</td></tr><tr><td>`filters.values`</td><td>array</td><td>The options for facet filters on the listings page. Required if `filters.mode = show_some`</td><td>Conditional</td></tr><tr><td>`filters.values.*.name`</td><td>string</td><td>The name of the facet filter, e.g. `Category`, `Price`, etc...</td><td>Yes</td></tr><tr><td>`filters.values.*.collapsed`</td><td>boolean</td><td>Whether to collapse the facet filter or not</td><td>Yes</td></tr><tr><td>`sort_bys`</td><td>array</td><td>An array of the applied sorts on the listings page (e.g., name-az, name-za, price-low, price-high, etc...)</td><td>No</td></tr><tr><td>`per_page`</td><td>int</td><td>The per page of the listings page (defaults to 24)</td><td>No</td></tr></tbody></table>

##### SEO

<table border="1" id="bkmrk-name-type-descriptio-7" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`heading`</td><td>string</td><td>The SEO Heading</td><td>No</td></tr><tr><td>`page_title`</td><td>string</td><td>The SEO Page Title</td><td>No</td></tr><tr><td>`meta_description`</td><td>string</td><td>The SEO Meta Description</td><td>No</td></tr><tr><td>`canonical`</td><td>string</td><td>The SEO Canonical</td><td>No</td></tr><tr><td>`noindex`</td><td>boolean</td><td>The SEO No Index</td><td>No</td></tr><tr><td>`nofollow`</td><td>boolean</td><td>The SEO No Follow</td><td>No</td></tr></tbody></table>

##### Additional Attribute

<table border="1" id="bkmrk-name-type-descriptio-8" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`key`</td><td>string</td><td>The key of the additional attribute</td><td>Yes</td></tr><tr><td>`value`</td><td>string</td><td>The value of the additional attribute</td><td>Yes</td></tr></tbody></table>

##### Settings

Settings are grouped as key-value pairs.

- Use "\_" for ungrouped settings.
- Each group contains its own object of key-value pairs.

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

#### Example Request

```
POST /api/categories/
```

```json
{
    "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

```json
{
    "category": {
        "id": 1
    }
}
```

# Update Category Endpoint

#### Structure

##### Category

<table border="1" id="bkmrk-name-type-descriptio" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`name`</td><td>string</td><td>The name of the category</td><td>No</td></tr><tr><td>`parent`</td><td>string</td><td>The parent of the category</td><td>No</td></tr><tr><td>`slug`</td><td>string</td><td>The slug of the category, if not present it is auto-generated from name</td><td>No</td></tr><tr><td>`reference`</td><td>string</td><td>The reference of the category</td><td>No</td></tr><tr><td>`logic`</td><td>string</td><td>The logic of the rules for the category, and/or (defaults to or if not provided)</td><td>No</td></tr><tr><td>`visible`</td><td>boolean</td><td>The visibility of the category (defaults to `true`)</td><td>No</td></tr><tr><td>`featured_image`</td><td>object</td><td>The Image of the category</td><td>No</td></tr><tr><td>`tags`</td><td>array</td><td>An array of [Tag](https://support.aerocommerce.com/books/api/page/update-category-endpoint#bkmrk-tag) objects</td><td>No</td></tr><tr><td>`rules`</td><td>array</td><td>An array of Listing Page [Rule](https://support.aerocommerce.com/books/api/page/update-category-endpoint#bkmrk-rule) objects</td><td>No</td></tr><tr><td>`content`</td><td>object</td><td>The Listing Page [Content](https://support.aerocommerce.com/books/api/page/update-category-endpoint#bkmrk-content) of the category</td><td>No</td></tr><tr><td>`options`</td><td>object</td><td>The Listing Page [Options](https://support.aerocommerce.com/books/api/page/update-category-endpoint#bkmrk-options) of the category</td><td>No</td></tr><tr><td>`seo`</td><td>object</td><td>The [SEO](https://support.aerocommerce.com/books/api/page/update-category-endpoint#bkmrk-seo) of the category</td><td>No</td></tr><tr><td>`additional_attributes`</td><td>array</td><td>An array of [Additional Attribute](https://support.aerocommerce.com/books/api/page/update-category-endpoint#bkmrk-additional-attribute) objects</td><td>No</td></tr><tr><td>`settings`</td><td>object</td><td>A [Settings](https://support.aerocommerce.com/books/api/page/update-category-endpoint#bkmrk-settings) object with grouped key-value pairs</td><td>No</td></tr></tbody></table>

##### Image

<table border="1" id="bkmrk-name-type-descriptio-1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`src`</td><td>string</td><td>The source url of the image</td><td>Yes</td></tr></tbody></table>

##### Tag

<table border="1" id="bkmrk-name-type-descriptio-2" style="border-collapse: collapse; width: 100%; height: 111.789px;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Name**  
</td><td style="height: 29.7969px;">**Type**  
</td><td style="height: 29.7969px;">**Description**  
</td><td style="height: 29.7969px;">**Required**  
</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`name`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The name of the tag (e.g., Small or Red)</td><td style="height: 46.5938px;">Yes</td></tr><tr style="height: 35.3984px;"><td style="height: 35.3984px;">`group`</td><td style="height: 35.3984px;">object</td><td style="height: 35.3984px;">The tag group, see [Tag Group](https://support.aerocommerce.com/books/api/page/update-category-endpoint#bkmrk-tag-group)</td><td style="height: 35.3984px;">Yes</td></tr></tbody></table>

##### Tag Group

<table border="1" id="bkmrk-name-type-descriptio-3" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`name`</td><td>string</td><td>The name of the tag group (e.g., Size or Colour)</td><td>Yes</td></tr></tbody></table>

##### Rule

<table border="1" id="bkmrk-name-type-descriptio-4" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`type`</td><td>string</td><td>Rule type. Allowed values: `in_category`, `in_price_list`, `have_manufacturers`, `have_tags`, `price_between`, `reduced`, `published_within_days`, `published_within`</td><td>Yes</td></tr><tr><td>`requirement`</td><td>string</td><td>Requirement for the rule. Allowed values: `must`, `must_not`. Defaults to `must`</td><td>No</td></tr><tr><td>`logic`</td><td>string</td><td>How this rule combines with others. Allowed values: `and`, `or`. Defaults to `or`</td><td>No</td></tr><tr><td>`data`</td><td>object</td><td>Rule-specific data (see below). Keys vary depending on type</td><td>Yes</td></tr><tr><td>`data.tags`</td><td>array</td><td>An array of Tag ids (or names formatted as group|name). Required if `type = have_tags`</td><td>Conditional</td></tr><tr><td>`data.manufacturers`</td><td>array</td><td>An array of manufacturer ids (or names). Required if `type = have_manufacturers`</td><td>Conditional</td></tr><tr><td>`data.price_list`</td><td>string</td><td>Price list id (or name). Required if `type = in_price_list`</td><td>Conditional</td></tr><tr><td>`data.category`</td><td>string</td><td>Category id (or name/breadcrumb, e.g., Mens &gt; Coats). Required if `type = in_category`</td><td>Conditional</td></tr><tr><td>`data.days`</td><td>int</td><td>Number of days. Required if `type = published_within_days`</td><td>Conditional</td></tr><tr><td>`data.start_at`</td><td>timestamp</td><td>The start date. Required if `type = published_within`</td><td>Conditional</td></tr><tr><td>`data.end_at`</td><td>timestamp</td><td>The end date. Optional if `type = published_within`</td><td>Conditional</td></tr><tr><td>`data.min_price`</td><td>float</td><td>Minimum price (including tax) in store’s default currency, whole units only (e.g. pounds, not pence). Required if `type = price_between`</td><td>Conditional</td></tr><tr><td>`data.max_price`</td><td>float</td><td>Maximum price (including tax) in store’s default currency, whole units only. Required if `type = price_between`</td><td>Conditional</td></tr></tbody></table>

<p class="callout info"> The `rules` are nested within arrays to achieve grouping, see `rules` in Example Request for clarity</p>

##### Content

<table border="1" id="bkmrk-name-type-descriptio-5" style="border-collapse: collapse; width: 100%; height: 184.375px;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Name**  
</td><td style="height: 29.7969px;">**Type**  
</td><td style="height: 29.7969px;">**Description**  
</td><td style="height: 29.7969px;">**Required**  
</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">`summary`</td><td style="height: 29.7969px;">string</td><td style="height: 29.7969px;">The summary content</td><td style="height: 29.7969px;">No</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">`description`</td><td style="height: 29.7969px;">string</td><td style="height: 29.7969px;">The description content</td><td style="height: 29.7969px;">No</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">`small_image`</td><td style="height: 29.7969px;">object</td><td style="height: 29.7969px;">The Small [Image](https://support.aerocommerce.com/books/api/page/update-category-endpoint/#bkmrk-image)</td><td style="height: 29.7969px;">No</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">`medium_image`</td><td style="height: 29.7969px;">object</td><td style="height: 29.7969px;">The Medium [Image](https://support.aerocommerce.com/books/api/page/update-category-endpoint/#bkmrk-image)</td><td style="height: 29.7969px;">No</td></tr><tr style="height: 35.3906px;"><td style="height: 35.3906px;">`large_image`</td><td style="height: 35.3906px;">object</td><td style="height: 35.3906px;">The Large [Image](https://support.aerocommerce.com/books/api/page/update-category-endpoint/#bkmrk-image)</td><td style="height: 35.3906px;">No</td></tr></tbody></table>

##### Options

<table border="1" id="bkmrk-name-type-descriptio-6" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`categories.mode`</td><td>string</td><td>Categories filter display mode. Allowed values: `show_all`, `hide_all`, `show_some`. Default: `show_all`</td><td>No</td></tr><tr><td>`categories.values`</td><td>array</td><td>An array of category ids (or names/breadcrumbs, e.g. Mens &gt; Coats) to show. Required if `categories.mode = show_some`</td><td>Conditional</td></tr><tr><td>`filters.mode`</td><td>int</td><td>Facet filters display mode. Allowed values: `show_all`, `hide_all`, `show_some`. Default: `show_all`</td><td>No</td></tr><tr><td>`filters.values`</td><td>array</td><td>The options for facet filters on the listings page. Required if `filters.mode = show_some`</td><td>Conditional</td></tr><tr><td>`filters.values.*.name`</td><td>string</td><td>The name of the facet filter, e.g. `Category`, `Price`, etc...</td><td>Yes</td></tr><tr><td>`filters.values.*.collapsed`</td><td>boolean</td><td>Whether to collapse the facet filter or not</td><td>Yes</td></tr><tr><td>`sort_bys`</td><td>array</td><td>An array of the applied sorts on the listings page (e.g., name-az, name-za, price-low, price-high, etc...)</td><td>No</td></tr><tr><td>`per_page`</td><td>int</td><td>The per page of the listings page (defaults to 24)</td><td>No</td></tr></tbody></table>

##### SEO

<table border="1" id="bkmrk-name-type-descriptio-7" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`heading`</td><td>string</td><td>The SEO Heading</td><td>No</td></tr><tr><td>`page_title`</td><td>string</td><td>The SEO Page Title</td><td>No</td></tr><tr><td>`meta_description`</td><td>string</td><td>The SEO Meta Description</td><td>No</td></tr><tr><td>`canonical`</td><td>string</td><td>The SEO Canonical</td><td>No</td></tr><tr><td>`noindex`</td><td>boolean</td><td>The SEO No Index</td><td>No</td></tr><tr><td>`nofollow`</td><td>boolean</td><td>The SEO No Follow</td><td>No</td></tr></tbody></table>

##### Additional Attribute

<table border="1" id="bkmrk-name-type-descriptio-8" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`key`</td><td>string</td><td>The key of the additional attribute</td><td>Yes</td></tr><tr><td>`value`</td><td>string</td><td>The value of the additional attribute</td><td>Yes</td></tr></tbody></table>

##### Settings

Settings are grouped as key-value pairs.

- Use "\_" for ungrouped settings.
- Each group contains its own object of key-value pairs.

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

#### Example Request

```
PUT /api/categories/{id|name|breadcrumb}
```

```json
{
    "name": "Updated Mens",
    "slug": "mens-mens",
    "content": {
        "description": "Updated Mens"
    },
    "seo": {
        "heading": "Updated Mens"
    },
    "tags": [
        {
            "name": "Green",
            "group": {
                "name": "Colour"
            }
        }
    ]
}
```

#### Example Response

```json
{
    "category": {
        "id": 1
    }
}
```

# Delete Category Endpoint

#### Example Request

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

#### Example Response

```
204 No Content
```