CategoryList

Use the CategoryList resource to fetch multiple categories.

See Category Resource for information about related resources.

Note that the embedded items on each category in the list are limited to 25.

Schema type

Use category-list to reference this resource in the template schema.

Querying

Filters nullable

ids string[]

Array of Category ids to retrieve. Having this filter negates any sort filter defined on the same category-list resource.
```
  {
      "filters": {
          "ids": ["II4VPMMREFDLJ27TKULXOVMS", "NIJIIMAJJX4LZ4KF2MKHTGNY"]
      }
  }
```
location_id string
- Default: Catalog Shipping Location ID
id of Location to scope a category to. The category data received will be based off of the category’s configuration at the given location. Must be used in conjunction with filters.id or filters.ids 5
```
  {
      "filters": {
          "ids": ["II4VPMMREFDLJ27TKULXOVMS"],
          "location_id": "location_id"
      }
  }
```

search string

Returns categories that match the search term.

  {
      "filters": {
          "search": "t-shirts"
      }
  }

status string[]
- status.in_stock string
  
  Filters list of items attached to the category depending on inventory stock status. Items denoted as sold out will be removed from the items list attached to the category
```
  {
      "filters": {
          "status": [
              "in_stock"
          ]
      }
  }
```
availability array[]

Key values by and time are required.
- availability.by string
  
  Valid values: ordering, deliver, ready
  
  Provides the next available time period that a category will be available at for each given fulfillment method by the ordering or deliver time, or the time that the category will be ready by.
- availability.time array[]
  - availability.time.from string
    - Default: “now”
    If set to now, the time object works off of the current timestamp at the time of the request.
    
    If set to a 24 hour (e.g. 14:30:00) or UNIX (e.g. 1699073149) timestamp, the time object works off of the defined timestamp.
Availability Example
```
      ```
      {
          // Provides a category's next availability window
          "availability": {
              "by": "ordering", // Find categories by "ordering" time
              "time": {
                  "from": "now", // use the current time
                  "from": "14:00:00", // or 24 hour timestamp (2pm)
              }
          }
      }
      ```
```

Optional

includes string[]
- Default: ['images', 'storefront_assignments', 'product_count', 'subcategory_count', 'products', 'products.options', 'products.images', 'products.media_files', 'products.modifiers', 'products.skus', 'products.placeholder_image', 'products.pickup_locations', 'products.delivery_locations', 'products.locations', 'products.categories', 'products.fulfillment', 'products.discounts']
To reduce the size of the API response, you can specify which includes to be returned in the request payload
```
  {
      "includes": [
          "images",
          "products",
          "products.images"
      ]
  }
```

List Rendering

When filters.ids is not defined, the first page of categories will return as a result.

{ // Fetches first page of categories and filters for out any out of stock items within each category
    "filters": {
        "status": [
            "in_stock"
        ]
    }
}

Pagination

pagination.page_size number

Default: 100

Control the page size of the category list request. Does not apply to filters.ids requests.

  {
      "filters": {
          "status": [
              "in_stock"
          ]
      },
      "pagination": {
          "page_size": 50
      }
  }

pagination.page number
- Default: 1
Control the page number of the category list request. Does not apply to filters.ids requests.
```
  {
      "pagination": {
          "page_size": 50,
          "page": 2
      }
  }
```
pagination.meta_name string nullable

Used to set the name for this resource when loaded via a resource function for use with the paginate_meta function. Note that this field is ignored for resources loaded via a template’s schema, as the resource name itself is used for the paginate_meta function.
pagination.page_query_param string
- Default: {property_name}_page
Control the query param that loads the page number of the category list. By default, the query param used is the name of the property with _page attached as a suffix. Does not apply to filters.ids requests.
```
  {
      "all_categories": {
          "pagination": {
              "page_size": 50,
              "page_query_param": "page"
          }
      }
  }
```
Results in mysite.com/shop?page=4 to load the fourth page of the correlating category list. By default, the pagination query parameter would be all_categories_page if no query parameter override was provided

Sorting

sort.by string Sort categories in response by a given term.

  {
      "filters": {
          "ids": ["3", "5", "7", "9"]
      },
      "sort": {
          "by": "name"
      }
  }

Valid terms:

      - name

sort.order string

Default: “asc”

Sort order of categories in response.

  {
      "sort": {
          "order": "desc"
      }
  }