• Version: 1.2.0

Collections

Collections allow you to organize products into sets of items. This is an additional descriptor for products, separate from categories and brands. Collections can be given their own webpage within a store by referencing the slug data field. In Moltin, collections are flows-based data structures, which means that they are flexible data structures and can be modified on the fly. Collection flows have the following fields by default:

Key Type Required Unique Details
id Integer No Yes Automatically populated when you create the collection.
title String Yes Yes The full name of this collection.
slug String Yes Yes Often included in the URL for this collection.
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 collection. Usually displayed on the collection webpage.
created_at String No No Automatically populated when you create the collection.
updated_at String No No Automatically populated when you modify the collection.

Before using collections, you’ll need to create them with the https://api.molt.in/v1/collections endpoint. Collections can be associated with products so that collection webpages can produce a list of all associated 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 Collection

If you want to use collections with your products, you will need to add that data to your store. By default, new stores contain no collections. Every collection 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/collections \
  -H "Authorization: Bearer XXXX" \
  -d "title=Coffemakers We Love" \
  -d "slug=coffee_love" \
  -d "status=1" \
  -d "description=These coffeemakers proved themselves worthy in our taste tests."

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

{
  "status":true,
  "result":
  {
    "id":"1048614635990679658",
    "order":null,
    "created_at":"2015-08-10 16:37:05",
    "updated_at":"2015-08-10 16:37:05",
    "slug":"coffee_love",
    "status":
    {
      "value":"Live",
      "data":
      {
        "key":"1",
        "value":"Live"
      }
    },
    "title":"Coffemakers We Love",
    "description":"These coffeemakers proved themselves worthy in our taste tests.",
    "images":[]
  }
}

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

Retrieve Collection Information

Once you have created some collections for your store, you have two methods to retrieve that information. The first requires that you know the ID number of the collection that you want, and it returns solely the information for that one collection. The second returns an array of collections 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 Collection by ID

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

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

On success, this call returns 200 OK and the collection information for the selected ID number.

Retrieve a List of All Collections

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

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

On success, this call returns 200 OK and an array of collection information, as shown in the Create a Collection section. You can pass any data field values to limit the results, as shown in the next section.

Search for Collections by Field Values

Instead of returning all of your collections, you can return only collections that match on specified field values.

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

Again, a successful call returns 200 OK and an array of collection information, even if this call only returns one collection.

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

Edit a Collection

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

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

curl -X PUT https://api.molt.in/v1/collections/:id \
	-H "Authorization: Bearer XXXX" \
	-d "description=We really like these coffeemakers. So will you."

On success, this returns 200 OK and the updated collection information.

Delete a Single Collection

To remove a collection, you use the same collections/{ID number} endpoint we used to retrieve a single collection, 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/collections/1048614635990679658
	-H "Authorization: Bearer XXXX"

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

{
	"status":true,
	"message":"Collection removed successfully"
}

Get a list of collection fields

You can get a list of collection 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 = Collection::Fields(null, true);

echo '<form method="collection/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>';