Last updated: 20 Feb 2018
Promotions are a great lever to encourage sales, reward customers, or attract new buyers. Our new promotions feature allows you to provide discounts to your customers — either as a percentage or fixed amount off a cart.

The initial offering is quite simple — it reflects the approach that we’ve used on the promotion system to try and make it flexible, yet robust.

By defining a promotion and a code, you put in place the ability to offer discounts to customers - applied directly to their shopping carts. The promotions you create will require codes to be attached to them, and these codes are subsequently used by your customers (or your own system) to apply promotions to cart and the subsequent discounts stipulated.

Let’s dive right in and see what the system needs to get started.

Creating promotions

You create your own promotions. The request will be something like:


  curl -X POST \
    -H "Authorization: Bearer 0bfcb98e2d903c680775e209cde36a73c5d82000" \ 
    -H "Content-Type: application/json" \
    -d $'{
     "data": {
       "name": "Promo #1",
       "description": "Initial Promotion",
       "enabled": true,
       "promotion_type": "fixed_discount",
             {"currency":"USD", "amount":2000},
       "start":"2017-05-12 15:04",
       "end":"2019-10-12 15:04"

So, let’s look at this request.

The main points are the promotion_type and schema properties. These are the ones that decide what/how the promotion you create are applied.

At present, Moltin offers two types of discount, fixed_discount and percentage_discount. Fixed discount will apply the amount specified in the currency value within the schema, it will apply that value blindly. A percentage discount will apply the percentage defined in the schema based on the total value of the cart.

These two properties exist so that additional types of promotion added to our system are simple and will not affect already existing types. E.g. we envisage releasing a x_for_y type soon that will allow offers such as 3 for 2 or 2 for 1 to be produced, this will obviously need more information within the schema, currency will be useless but productID will be very relevant. Hopefully, you can see quite early why we have adopted this approach. I’m sure people will have all manner of ideas on what kind of offers they’d like to create with some unusual scenario surrounding them — we believe we can deliver solutions to some quite complex scenarios using this simple structure.

  • The name and description are essential for you to identify what your promotion is/does so be sure to use sensible information here.
  • The enabled flag allows you to switch the promotion on/off without having to touch the start/end times (this is important as you will see when updating end times).
  • The promotion will not become active until the start date/time defined.
  • The promotion will cease to be active once the end date/time has passed — an expiry if you will — even if enabled is still true.

All these properties are required in order to create a promotion.


So a brief look at creating promotions — but how do you apply promotions to your Moltin cart? Codes…

A promotion is located through a code — we allow you to attach codes to your promotions via:


  curl -X POST{PRODUCT_ID}/codes \
    -H "Authorization: Bearer 0bfcb98e2d903c680775e209cde36a73c5d82000" \
    -H "Content-Type: application/json" \
    -d $'{
     "data": {
         { "code": "abcdef" },
         { "code": "uvwxyz" }

This may look odd, ‘why not just pass a list of codes?’ you say, well… You may want to restrict the number of times a code is used, or by whom. In the not too distant future, these features will appear, and they will be delivered by associating data with each code.

You will, however, need to see those codes so you can dish them out to whoever you wish. To do that:

  curl -X GET{PRODUCT_ID}/codes \
    -H "Authorization: Bearer 0bfcb98e2d903c680775e209cde36a73c5d82000"

Moltin doesn’t currently generate codes automatically (we might enable this in the future but not now - you generate them yourself) — but we do ensure that the codes submitted are unique across you active promotions so no clashes will occur.

Note Updating End Time

The Moltin system ensures that all your active promotion codes are unique, so preventing any collision or confusion when using codes. In order to guarantee this, we will truncate any codes attached to a promotion when that promotion is re-enabled via updating an end time that expired to one that is in the future.

Any codes that promotion had will be removed and you will have to generate new codes to attach to the promotion.

Using Promotions

You’ve set up some promotions and you’ve attached some codes to them so now we need to give your customers some discounts…

To apply a promotion to a customer’s shopping cart you need to add a promotion item to that cart.

  curl -X POST{CART_ID}/items \
    -H "Authorization: Bearer 0bfcb98e2d903c680775e209cde36a73c5d82000" \
     -H "Content-Type: application/json" \
     -d $'{
     "data": {

Internally, the cart system will get the promotion and apply a discount if it gets a favourable response.

That sound reasonably simple? We hope so.

Over time we envisage the promotion system to expand its offering and you will play a part in that - we need you to tell us what kind of promotions you feel would be useful - not just to you but to others too! We want everyone to benefit from Moltin… Add your feedback and ideas to the forum to influence the promotions roadmap.