This post will show you how to organize your store into a clear, understandable structure, making it easier for your customers to browse and therefore buy your products.

Before we begin, if you’re not too technical you can complete all the actions explained in this post via our admin dashboard without having to write any code or make any requests directly to the Moltin API.

Categories

If you’re selling more than a handful of products, the ability to navigate through your inventory is essential when helping your customers shop in your store. To do this, you should provide categories and subcategories that direct them to their goals in a clear and understandable fashion.

Creating a category

Endpoint: https://api.moltin.com/v1/categories

A POST request to the endpoint with the following payload should create a Category.1 2

Key Type Description
title String Category Name
description String Category Description
status Integer The status of the Category 0 = draft, 1 = live
parent String The ID of the parent Category, null if there is no parent
slug String The Slug/URI segment of the category, must be unique

A successful response on Category creation will look something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
    "status": true,
    "result": {
        "id": "927354786238176327",
        "order": null,
        "created_at": "2016-01-03 11:20:00",
        "updated_at": "2016-01-03 11:20:00",
        "parent": null,
        "slug": "category",
        "status": {
            "value": "Draft",
            "data": {
                "key": "0",
                "value": "Draft"
            }
        },
        "title": "Category",
        "description": "A simple category",
        "images": []
    }
}

Great! That’s our first Category created…

Editing a category

At some point, you will probably want to edit a category you’ve created previously.2

Endpoint: https://api.moltin.com/v1/categories/:id

Using the result from the Create Category section, here our endpoint would be: https://api.moltin.com/v1/categories/927354786238176327

In this case, we submit a PUT request. The parameters are the same but you do not have to provide all fields - only those you want to update. So let’s just update the Title and Description and set the Category live…

Key Value
title Terrapins
description Repites that love water
status 1

A successful response would look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
    "status": true,
    "result": {
        "id": "927354786238176327",
        "order": null,
        "created_at": "2016-01-03 11:20:00",
        "updated_at": "2016-01-03 12:00:00",
        "parent": null,
        "slug": "category",
        "status": {
            "value": "Live",
            "data": {
                "key": "1",
                "value": "Live"
            }
        },
        "title": "Terrapins",
        "description": "Reptiles that love water",
        "images": []
    }
}

Deleting a category

You may find you want to delete a Category as it’s no longer needed.2

Endpoint: https://api.moltin.com/v1/categories/:id

No payload is required for submitting a DELETE request. You are substituting the ID with the ID of the Category you wish to remove. On successful removal you should get a response similar to this:

1
2
3
4
{
    "status": true,
    "message": "Category removed successfully"
}

Get Your category tree

All the categories and subcategories you’ve created now form a Category Tree. This is a nested data structure of the categories where subcategories are stored as children of their parent category.

Now you should be ready to grab your Category Tree so you can use it as the navigation aide for your customers.

Endpoint: https://api.moltin.com/v1/categories/tree

A GET request with no payload will return your tree structure.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{
    "status": true,
    "result": [
        {
            "id": "927354786238176327",
            "order": null,
            "created_at": "2016-01-03 11:20:00",
            "updated_at": "2016-01-03 12:00:00",
            "parent": null,
            "slug": "terrapins",
            "status": {
                "value": "Live",
                "data": {
                    "key": "1",
                    "value": "Live"
                }
            },
            "title": "Terrapins",
            "description": "Reptiles that love water",
            "images": []
        },
        {
           "id": "927354786238155242",
           "order": null,
           "created_at": "2016-01-03 13:00:00",
           "updated_at": "2016-01-03 13:00:00",
           "parent": null,
           "slug": "cats",
           "status": {
               "value": "Live",
               "data": {
                   "key": "1",
                   "value": "Live"
               }
           },
           "title": "Cats",
           "description": "Cats hate water",
           "images": []
        }
    ],
    "pagination": null
}

Any child categories will be included within the parent under the “children” property which will be a Collection of JSON objects.

Get a category by ID

If you want details of one single Category you can retrieve this information.

Endpoint: https://api.moltin.com/v1/categories/:id

A GET request without any payload should return a response similar to the below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
    "status": true,
    "result": {
        "id": "927354786238176327",
        "order": null,
        "created_at": "2016-01-03 11:20:00",
        "updated_at": "2016-01-03 12:00:00",
        "parent": null,
        "slug": "category",
        "status": {
            "value": "Live",
            "data": {
                "key": "1",
                "value": "Live"
            }
        },
        "title": "Terrapins",
        "description": "Reptiles that love water",
        "images": []
    },
    "pagination": {
        "items": {
            "previous": false,
            "next": false
        }
    }
}

Collections

Collections are very similar to Categories and the anatomy of the requests used in their administration should look familiar. There is one key difference however, collections can not create a hierarchical structure or to put that in simpler terms; collections cannot be nested.

Have you got a sale on or a new range of summer clothing? Promoting these on your site is not practical using categories and so you should consider using Collections. Collections allow you to create a grouping of items for this purpose. You can then promote anywhere on your site without destroying your well-organized Category structure.

Creating a collection

Endpoint: https://api.moltin.com/v1/collections

A POST request to the endpoint with the following payload should create a Collection.2

Key Type Description
title String Collection Name
slug String The Slug/URI segment of the Collection, must be unique
status Integer The status of the Collection 0 = draft, 1 = live
description String A description of the Collection

The response from a successful Collection creation request will look like the below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "status": true,
  "result": {
    "id": "1244654767487395243",
    "order": null,
    "created_at": "2016-01-25 13:34:26",
    "updated_at": "2016-01-25 13:34:26",
    "slug": "summer-range",
    "status": {
      "value": "Live",
      "data": {
          "key": "1",
          "value": "Live"
      }
    },
    "title": "Summer Range",
    "description": "Our new range for the summer",
    "images": []
  }
}

Edit a Collection

If you need to update a Collection, as with editing a category, simply pass the properties you wish to amend to the following endpoint.2

Endpoint: https://api.moltin.com/v1/collections/:id

id - the Collection ID to be edited.

PUT using the same parameters as those for Category Creation. Remember you only need send the property you need to update.

Key Value
title Autumn Collection
slug autumn-collection
status 1
description We missed the summer.

The response from a successful Collection update request will look like the below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "status": true,
  "result": {
    "id": "1244654767487395243",
    "order": null,
    "created_at": "2016-01-25 13:34:26",
    "updated_at": "2016-06-30 08:49:45",
    "slug": "autumn-collection",
    "status": {
      "value": "Live",
      "data": {
        "key": "1",
        "value": "Live"
      }
    },
    "title": "Autumn Collection",
    "description": "We missed the summer",
    "images": []
  }
}

Deleting a Collection

You can also delete a Collection when it is no longer needed or used.2

Endpoint: https://api.moltin.com/v1/collections/:id

DELETE - no parameters are required.

A successful deletion will return a response like:

1
2
3
4
{
  "status": true,
  "message": "Collection deleted successfully"
}

If you receive this response your Collection has been permanently removed.

Get Collections

Now we’ve done the admin side of Collections, it’s time to use them on your store.

Endpoint: https://api.moltin.com/v1/collections

GET request to the endpoint with no parameters.

The response will look something like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
{
  "status": true,
  "result": [
    {
      "id": "1167247800228905834",
      "order": null,
      "created_at": "2016-01-21 09:00:02",
      "updated_at": "2016-01-21 09:02:07",
      "slug": "collection-1",
      "status": {
        "value": "Live",
        "data": {
          "key": "1",
          "value": "Live"
        }
      },
      "title": "Collection 1",
      "description": "B Collection schnizzle",
      "images": []
    },
    {
      "id": "1166726396425274217",
      "order": null,
      "created_at": "2016-01-20 15:44:06",
      "updated_at": "2016-01-20 15:44:06",
      "slug": "collection-a",
      "status": {
        "value": "Live",
        "data": {
          "key": "1",
          "value": "Live"
        }
      },
      "title": "Collection A",
      "description": "A Collection",
      "images": []
    }
  ],
  "pagination": {
    "total": 2,
    "current": 2,
    "limit": 15,
    "offset": 0,
    "from": 1,
    "to": 2,
    "offsets": {
      "first": false,
      "previous": false,
      "next": false,
      "last": false
    },
    "links": {
      "first": false,
      "previous": false,
      "next": false,
      "last": false
    }
  }
}

That’s it, all your Collections will be in a paginated response. You can use this to display the Collections in whichever way works best for you, this could be a landing page, a smaller section on your site pages or even part of your navigation structure.

Get Collection By ID

Should you require the information from just one Collection, a similar process is followed.

Endpoint: https://api.moltin.com/v1/collections/:id

GET request to the endpoint with no parameters.

Simply provide the ID of the Collection you wish to retrieve and you should receive a response like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "status": true,
  "result": {
    "id": "1166726396425274217",
    "order": null,
    "created_at": "2016-01-20 15:44:06",
    "updated_at": "2016-01-20 15:44:06",
    "slug": "collection-a",
    "status": {
      "value": "Live",
      "data": {
        "key": "1",
        "value": "Live"
      }
    },
    "title": "Collection A",
    "description": "A Collection",
    "images": []
  },
  "pagination": {
    "items": {
      "previous": false,
      "next": false
    }
  }
}

All of the above should provide you with the tools you need to hit the ground running with your Collections.

###Images You will have noticed that the responses from both Categories and Collections include a property called “images”. Within the Moltin ecosystem you can attach images to almost anything. But how?

Attaching an Image

The file upload endpoint is our friend here.2

Endpoint: https://api.moltin.com/v1/file

A POST request to the endpoint using the “multipart/form-data” content-type header should also be accompanied by the following parameters:

Key Type Description
file String The file to upload (the name of your input type=”file” field)
name String A name you wish to give the file
assign_to Integer OPTIONAL the ID of the flow entry you wish to attach the file to

The last field assign_to is the important element here as it’s the one we use to tell the system what to associate the file with. In our case we would like to attach it to a Collection so using the ID of the Collection we created initially enter “1244654767487395243” in this field.

A successful response would yield something like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "status": true,
  "result": {
    "id": 2544673952435476748,
    "url": {
      "http": "http://commercecdn.com/1/db072334-3f20-4801-8e22-2a4d205e4f67.jpeg",
      "https": "https://commercecdn.com/1/db072334-3f20-4801-8e22-2a4d205e4f67.jpeg"
    },
    "segments": {
      "domain": "commercecdn.com/",
      "suffix": "/1/db072334-3f20-4801-8e22-2a4d205e4f67.jpeg"
    }
  }
}

Now - if we make a request to that Collection we created earlier, we should receive something like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "status": true,
  "result": {
    "id": "1244654767487395243",
    "order": null,
    "created_at": "2016-01-25 13:34:26",
    "updated_at": "2016-01-25 13:34:26",
    "slug": "summer-range",
    "status": {
      "value": "Live",
      "data": {
          "key": "1",
          "value": "Live"
      }
    },
    "title": "Summer Range",
    "description": "Our new range for the summer",
    "images": ["http://commercecdn.com/1/db072334-3f20-4801-8e22-2a4d205e4f67.jpeg"]
  }
}

Now you should successfully be able to add Categories and Collections to your store!

  1. If you specified a parent Category then that field in the response should include that information in the parent field.

  2. You will need to be authenticated with the correct grant type (e.g. client credentials) before making this request. 2 3 4 5 6 7

Ian Wood

Written by Ian Wood - Platform Engineer @ Moltin