• Version: 1.2.0

Products

Products are the building blocks of any eCommerce system. They represent the inventory that you sell to customers. Products are flows based data structures that store information relating to your inventory. These items can be added to your cart and then sold using the checkout endpoints, specific items can also be set to catalog only to be used for display purposes only.

Products are able to support sizes, colours, etc. using the modifier and variation system, which turns the parent product into a container and only allows the children to be sold. These child products can be totally customised using sku, title, price, stock levels, description and images.

Product flows have the following fields by default:

Key Type Required Unique Details
status Choice Yes No Choices available are 0 (Draft) and 1 (Live).
id Integer No Yes Automatically populated when you create the product.
order Integer/Multiple No Yes Will return both the ID number of the order, if applicable, and links to the JSON array details.
created_at String No No Automatically populated when you create the product.
updated_at String No No Automatically populated when you modify the product.
sku String Yes Yes -
title String Yes No -
slug String Yes Yes Often included in the URL for this product.
price Float* Yes No The base price of the product.
sale_price Float* No No The price when on sale.
category Integer/Multiple Yes No Pass the ID number of the category when creating a product. Returns both the ID number and a JSON array with the category details.
stock_level Integer Yes No The amount of product in stock.
stock_status Choice Yes No Choices available are 0 (Unlimited), 1 (In Stock), 2 (Low Stock), 3 (Out Of Stock), 4 (More Stock Ordered) and 5 (Discontinued).
description String Yes No You can enter HTML tags to format this description.
requires_shipping Choice Yes No Indicate whether orders with this product will require a shipping object to calculate the price with shipping and handling charges. Choices available are 0 (No) and 1 (Yes).
weight Float* No No -
height Float* No No -
depth Float* No No -
catalog_only Choice Yes No Indicates whether this product is only listed in the catalog and not for sale. Choices available are 0 (No) and 1 (Yes).
tax_band Integer/Multiple Yes No Links this product to a tax. Set this value using the ID number of a tax band that you have created.
collection Integer/Multiple No No The collection that this product is part of. Set this using the collection ID number.
brand Integer/Multiple No No The brand that this product is associated with. Set this using the brand ID number.
is_variation Boolean No No Returns whether this product is a variation of a parent product.
modifiers Array No No Returns the modifiers available on this product.
images Array No No Returns an array of assigned images for this product.

*All Float values are limited to two decimal places.

You can add additional fields to individual products through the modifier and variation system. Modifiers are additional qualities a product could have - like the color - and variations are the specific values of the modifier - such as red, black, and green. So each modifier needs to have one or more variants associated with it. When you create a modifier and its variants, the affected product becomes a container for child products, one for each variant associated with a particular modifier.

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

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 Product

For every item in your catalog, regardless of whether it is currently available or is catalog-only, you will need to create a product for it. POST the product data to the https://api.molt.in/v1/products. Every product 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/products \
	-H "Authorization: Bearer XXXX" \
	-d "sku=1893015" \
	-d "title=12-Cup Coffeemaker" \
	-d "slug=12cup-coffemaker" \
	-d "price=49.99" \
	-d "status=1" \
	-d "category=1018996345081430307" \
	-d "stock_level=0" \
	-d "stock_status=3" \
	-d "description=Brew delicious coffee with this 12-cup coffeemaker. Have a fresh cup in the morning! Have coffee right now! I need more coffee!" \
	-d "requires_shipping=1" \
	-d "tax_band=1019004846583317128" \
	-d "catalog_only=1"

You will need to create a tax and category before creating any products.

On success, this call returns a 201 Created HTML status code and the product information for the newly created product, 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":"1019656230785778497",
		"order":null,
		"created_at":"2015-07-01 17:41:28",
		"updated_at":"2015-07-01 17:41:28",
		"sku":"1893015",
		"title":"12-Cup Coffeemaker",
		"slug":"12cup-coffeemaker",
		"sale_price":0,
		"status":
		{
			"value":"Live",
			"data":
			{
				"key":"1",
				"value":"Live"
			}},
			"category":
			{
				"value":"Home Appliances",
				"data":
				{
					"1018996345081430307":
					{
						"id":"1018996345081430307",
						"order":null,
						"created_at":"2015-06-30 19:50:24",
						"updated_at":"2015-06-30 19:50:24",
						"parent":null,
						"slug":"home-appliances",
						"status":
						{
							"value":"Live",
							"data":
							{
								"key":"1",
								"value":"Live"
							}
						},
						"title":"Home Appliances",
						"description":"Appliances for your home"
					}
				}
			},
			"stock_level":0,
			"stock_status":
			{
				"value":"Out Of Stock",
				"data":
				{
					"key":"3",
					"value":"Out Of Stock"
				}
			},
			"description":"Brew delicious coffee with this 12-cup coffeemaker. Have a fresh cup in the morning! Have coffee right now! I need more coffee!",
			"requires_shipping":
			{
				"value":"Yes",
				"data":
				{
					"key":"1",
					"value":"Yes"
				}
			},
			"weight":0,
			"height":0,
			"width":0,
			"depth":0,
			"catalog_only":
			{
				"value":"Yes",
				"data":
				{
					"key":"1",
					"value":"Yes"
				}
			},
			"tax_band":
			{
				"value":"none",
				"data":
				{
					"id":"1019004846583317128",
					"title":"none",
					"description":null,
					"rate":0,
					"created_at":null,
					"updated_at":null
				}
			},
			"collection":null,
			"brand":null,
			"price":
			{
				"value":"\u00a349.99",
				"data":
				{
					"formatted":
					{
						"with_tax":"\u00a349.99",
						"without_tax":"\u00a349.99",
						"tax":"\u00a30.00"
					},
					"rounded":
					{
						"with_tax":49.99,
						"without_tax":49.99,
						"tax":0
					},
					"raw":
					{
						"with_tax":49.99,
						"without_tax":49.99,
						"tax":0
					}
				}
			},
			"is_variation":false,
			"modifiers":[],
			"images":[]
		}
	}
}

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

Retrieve Product Information

Once you have created the products in your catalog, you have two methods to retrieve that information. The first requires that you know the ID of the product that you want, and it returns solely the information for that one product. The second returns an array of products 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 Product by ID

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

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

A successful call returns a 200 OK status code and the product information for the selected ID number.

Retrieve a List of All Products

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

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

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

Search for Products by Field Values

Instead of returning all of your products, you can only return products that match on specified field values. This lets you do things like return products in a category or see which products are out of stock.

curl -X GET https://api.molt.in/v1/products/search/?stock_status=3 \
  -H "Authorization: Bearer XXXX"

Again, this returns 200 OK an array of product information, even if this call only returns one product.

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

Edit a Product

To change one or more values in a single product, use a PUT call with the products/{ID number} endpoint. You can change most field values through this method, including changing a product from draft to live status, updating sale prices, or indicating stock levels.

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

curl -X PUT https://api.molt.in/v1/products/1019656230785778497 \
	-H "Authorization: Bearer XXXX" \
	-d "collection=1019731797556069242"

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

Delete a Single Product

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

If successful, this call returns 200 OK and the following:

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