This information is specific to the deprecated version one. For more up-to-date details, see our Developer Portal.
The traditional modifier on a product is the Variant. This is a modifier which will fundamentally change the base product. So if we have a shop that sells pizzas online, we’d probably have a few variants in there, one which contains variants for your base size (7”, 10”, 12”), one for your crust (“Regular”, “Thin”, “Deep Pan” etc).
Welcome to the Matrix
Creating these as variant modifiers will create what we call a product matrix, which is essentially every combination that can be made.
Each variation you create can have a mod_price which affects the price in the matrix when it is created. Clearly, your 12” pizza costs more than a 7”, so your mod_price will reflect the base product and by extension what it costs to produce.
If you consider the following products, these can all be different prices if we added these modifiers via the dashboard or the API:
When the matrix has been created, you can then control each of the products via the API as if they were a regular product.
Note: whilst pizza dough would probably be fresh; if you applied the same logic to something like t-shirts, you can quickly see why having individual products with their own stock levels can be beneficial.
Enter the Single
Let’s say we now want to create a toppings selection to upsell our pizza. Adding a variant no longer makes sense - depending on how many toppings you have, there will very quickly be thousands of different combinations that could be selected and you clearly don’t want to manage those as individual products.
So this is where Singles comes in - they allow you to add optional variations to your products which don’t reflect a change in the base product - after all, you’re just sprinkling some chilies, pepperoni, ham, pineapple etc on top of a base product without changing that base product, regardless of whether it is a 7” Regular or a 12” Deep Pan.
By using Singles, we can now exponentially create the number of possible variations and maintain our simple base products. We simply use the single type:
curl -X POST https://api.molt.in/v1/products/1/modifiers \ -H "Authorization: Bearer XXXX" \ -d "title=Toppings" \ -d "type=single"
Then add our toppings as variations:
curl -X POST https://api.molt.in/v1/products/1/modifiers/<toppings_modifier_id> \ -H "Authorization: Bearer XXXX" \ -d "title=Ham" \ -d "mod_price=+0.75"
Linking a Single to a product
When you create (or update) your single variant you can also relate it to another product. This allows you to manage stock - if you only have limited number of pineapple portions to add to a pizza, you may want to make sure that no one can order them if stock runs out. By using the product parameter for the variation we will then use the stock level of that product to ensure that a customer can purchase this configuration. Each time an order is placed, the quantity of that single is then reduced and may trigger a low stock alert or be used for reporting.
curl -X POST https://api.molt.in/v1/products/1/modifiers/<toppings_modifier_id> \ -H "Authorization: Bearer XXXX" \ -d "title=Pineapple" \ -d "mod_price=+0.50" \ -d "product=<pineapple_product_id>"
Adding Singles to an Order
Your Singles are applied to a Cart before the order is placed and you simply need to use the correct format for applying them. We take care of converting the Cart to the order and the Singles are available on any items they have been applied to when you read your orders back.
Let’s add a 10” Deep Pan to our Cart alongside two portions of ham and a portion of pineapple:
curl -X POST https://api.molt.in/v1/carts/:cartIdent \ -H "Authorization: Bearer XXXX" \ -g \ -d "quantity=1" \ -d "id=5" \ -d "modifier[<toppings_modifier_id>][<ham_variation_id>]=2" \ -d "modifier[<toppings_modifier_id>][<pineapple_variation_id>]=1"
There are very few changes required on the client side to implement this new, feature-rich functionality as you can see from the above example. We simply use an array within the modifier to select which single variations you want in what quantity.
It has taken some time to implement because whilst the process is simple, you can see that in doing this, we have had to make significant updates to most parts of the Products, Carts and Orders logic in a backward compatible format, which required an extensive amount of testing.
As you may have read recently, we have secured funding and brought on additional engineers to develop the product and extend our tests to ensure that when we release features, we do so confidently without breaking backward compatibility. We’ve now done a significant portion of that and hope to iterate on these more quickly, so if you have any suggestions for features, you can always jump in the hub and pop something in the suggestions channel.
We’re extremely excited that Singles are now live and ready for you to use and we can’t wait to see how you start using them.