• Version: 1.2.0


Categories allow you to organize your products into hierarchical groups. That means these groups can also contain other categories, which can then be viewed in a tree structure. Categories provide more permanent classifications of products, while collections offer temporary and unordered descriptors, such as “Featured” and “Spring Collection”. In Moltin, categories are flows-based data structures, which means that they allow flexible data structures and can be modified on the fly. Category flows have the following fields by default:

Key Type Required Unique Details
id Integer No Yes Automatically populated when you create the category.
title String Yes Yes The full name of this category.
slug String Yes Yes Often included in the URL for this category.
parent Integer/Category object No No The parent category that contains this category.
status Boolean Yes No Choices available are 0 (Draft) and 1 (Live).
description String Yes No An HTML-enabled text field that gives more information about this category. Usually displayed on the category webpage.
created_at String No No Automatically populated when you create the category.
updated_at String No No Automatically populated when you modify the category.

Before using categories, you’ll need to create them with the https://api.molt.in/v1/categories endpoint. Once created, categories can be added to products.

Before you can use this (or any endpoint), you need to authenticate to get a bearer token.

This topic will cover the following processes:

Create a New Category

By default, new stores do not contain any categories, so you will need to create any that you want to use. Every category that you create must have data for at least the fields marked Required in the table above. You can put data fields in any order.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X POST https://api.molt.in/v1/categories \
	-H "Authorization: Bearer XXXX" \
	-d "slug=home-appliances" \
	-d "status=1" \
	-d "title=Home Appliances" \
	-d "description=Appliances for your home, naturally."

On success, this call will return a 201 Created HTML status and the category information for the newly created category, including any default or generated values. The object it returns looks like this by default (the data will be different, of course):

		"created_at":"2015-06-30 19:50:24",
		"updated_at":"2015-06-30 19:50:24",
		"title":"Home Appliances",
		"description":"Appliances for your home, naturally.",

The category actions below will return category information in this same format.

Retrieve Category Information

Once you have created categories for your products, you have two methods to retrieve that information. The first requires that you know the ID number of the category that you want, and it returns solely the information for that one category. The second returns an array of categories that you can limit by field values, specify a maximum number to return, and offset the start of the array. Using the last two options, you can paginate results by increasing the offset of a search by the previous maximum.

Retrieve a Single Category by ID

You can GET information for a single category by adding the category ID to the categories endpoint. No additional data fields are required.

curl -X GET https://api.molt.in/v1/categories/:id \
	-H "Authorization: Bearer XXX"

A successful call returns 200 OK and the category information for the selected ID number.

Retrieve a List of All Categories

Using the https://api.molt.in/v1/categories endpoint, you can return an array that contains all of the categories that you have created.

curl -X GET https://api.molt.in/v1/categories \
-H "Authorization: Bearer XXXX"

A successful call returns 200 OK and an array of category information, as shown in the Create a Category section. You can pass any category field values to limit the results, as shown in the next section.

Search for Categories by Field Values

Instead of returning all of your categories, you can only return categories that match on specified field values. This lets you do things like return categories based on the slug or whether they are live on the site.

curl -X GET https://api.molt.in/v1/categories/search/slug=home_appliances \
  -H "Authorization: Bearer XXXX"

Again, this will return 200 OK and an array of category information, even if this call only returns one category.

You can use multiple data fields to narrow down a search. However, each field must match exactly; otherwise, the search will return all categories.

If you want to return all products within a category, you will need to run a products search limited by the category data field.

Return the Full Categories Tree

One of the big benefits of categories over other product descriptors is that you can order them into a hierarchical tree. The Moltin API provides an endpoint that allows you to return categories within their tree structure.

curl -X GET https://api.molt.in/v1/categories/tree \
	-H "Authorization: Bearer XXXX"

Like the search endpoint, this will return 200 OKand an array of all categories. However, if a category is a parent to another category, all categories below it in the tree will be listed in a children array as part of that parent object. Child categories will only be listed once in this result - as part of their parent category’s children array.

Using Categories to build a simple two tier menu

Here is an example of how we could build a simple two tier menu using the category tree.

$tree = Category::Tree();

echo "<ul>";
foreach ($tree['result'] as $cat) {
 echo "<li><a href='/category/".$cat['slug']."'>".$cat['title']."</a></li>";
 if (! empty($cat['children'])) {
  echo "<ul>";
   foreach ($cat['children'] as $sub) {
    echo "<li><a href='/category/".$sub['slug']."'>".$sub['title']."</a></li>";
  echo "</ul>";
echo "</ul>";

Edit a Category

To change one or more values in a single category, use a PUT call with the categories/{ID number} endpoint. You can change most field values through this method, including changing a category from draft to live status, updating description copy, or changing the slug address.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X PUT https://api.molt.in/v1/categories/:id \
	-H "Authorization: Bearer XXXX" \
	-d "slug=appliances"

This will return 200 OK and the updated category information.

Delete a Single Category

To remove a category, you use the same categories/{ID number} endpoint we used to retrieve a single category, except we use the DELETE request method.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X DELETE https://api.molt.in/v1/categories/:id
	-H "Authorization: Bearer XXXX"

If successful, this call will return 200 OK and the following:

	"message":"Category removed successfully"

Get a list of category fields

You can get a list of category fields like so:

curl -X GET https://api.molt.in/v1/categories/fields
	-H "Authorization: Bearer XXXX"

You can also use this to build a simple form:

$fields = Category::Fields(null, true);

echo '<form method="category/create" action="post">';
foreach ( $fields as $field ) {
    echo '<label for="'.$field['slug'].'">'.$field['title'].'</label>';
    echo $field['input'];
echo '<button type="submit">Create</button>';
echo '</form>';