• Version: 1.2.0

Promotions

Promotions are experimental and not advised for production use as yet

Promotions are discounts that your store can automatically apply to customer orders based on flexible rules or customer-supplied discount codes. This powerful system lets you run free shipping offers, buy one get one free, price reductions, and employee discounts. With the rules engine, you can combine customer, cart, and product values to provide maximum flexibility in your store marketing. You can create and modify promotions using the https://api.molt.in/v1/promotions/carts endpoint.

Because promotions have so much flexibility, setting them up can be complicated. We’ll cover how to configure several types of promotions and provide examples that demonstrate real world uses.

Promotions are flows-based data structures, which means that they allow flexible data structures and can be modified on the fly. They have the following fields by default:

Key Type Required Unique Details
id Integer No Yes Automatically populated when you create the promotion.
order Integer/Array No No 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 promotion.
updated_at String No No Automatically populated when you modify the promotion.
title String Yes Yes The name of this promotion to display on your store.
from Date Yes No The earliest date that this discount can apply to orders.
to Date Yes No The last date on which this discount can apply to orders.
discount_code String No Yes A text string that a customer can enter in order to receive this discount. If you set this field, then the checkout will not apply this discount automatically. It will only be applied if a cart has a matching discount_field entry.
max_uses Integer No No The maximum number of times that this discount can be applied to all orders across all customers.
customer_uses Integer No No The maximum number of times that a single customer can redeem this discount.
customer_group Integer No No The ID number of the customer group to which the customer ordering must belong to.
status Choice Yes No Choices available are 0 (Draft) and 1 (Live). Draft promotions will not be applied to carts at checkout and discount codes will not affect order prices.
terminating Choice Yes No Whether this discount prevents other promotions from applying to this order. Choices available are 0 (additional discounts will be processed) and 1 (system will terminate processing further discounts).
persistent Choice Yes No Whether this discount will still apply if a higher priority discount terminated before it.
action String Yes No A string that represents the type of discount action to take. See the Promotion Types section below.
priority Integer No No The order in which to apply this discount. A lower value priority means a promotion processes first.
amount Float Yes No A value indicating the discount amount, percentage, or value. The meaning of this number differs depending on the type of action used.
max_quantity Integer No No The maximum discount that can be applied from this promotion. The exact function varies based on the action. See the Promotion Types section below.
trigger_quantity Integer No No For buy_x_get_y_free promotion actions, this indicates the number of matching products that the customer needs to buy in order to qualify for this promotion.
apply_to_shipping Choice Yes No Indicates whether the discount action applies to the shipping cost as well as the products subtotal.
shipping_methods Array No No An array of the ID numbers of the shipping methods that a free_ship discount applies to.
description String No No An HTML-enabled explanation of this promotion that can be displayed on your store.
match_rules Array No No A JSON array that indicates how cart attributes should be processed to qualify for this promotion. See the Create Rules section below.
match_items Array No No A JSON array that indicates how cart items - products - should be processed to qualify for this promotion. See the Create Rules section below.

Before using promotions, you’ll need to create them with the https://api.molt.in/v1/promotions/carts endpoint. Promotions without discount codes will be automatically applied based on the match_rules during checkout. To apply promotions with discount codes, your customers must be able to enter those codes before the checkout is processed.

Before you can use this (or any endpoint), you need to authenticate to get a bearer token.

This topic will cover the following processes:

Promotion Types

Each of the actions that you set will change how the promotion discount applies to orders, as well as how some of the other data fields function:

  • free_ship - Does not apply shipping costs if the customer selects one of the given shipping_methods. The max_quantity field indicates the maximum amount of shipping costs removed.
  • buy_x_get_y_free - If the customer purchases a certain numbers of products, set with trigger_quantity, they get some quantity free, set with amount. The max_quantity field indicates the total number of free items the customer can get.
  • discount_by_fixed - Deducts amount from the final product price. The max_quantity field indicates the total discount value for all product items.
  • discount_by_percent - Lowers the price of each matching product by amount percentage. Amount should be a number between 0 and 100. The max_quantity field is ignored.
  • discount_to_fixed - Sets the price of each matching item to amount. The max_quantity field is ignored.
  • discount_subtotal_fixed - Deducts amount from the final order subtotal. The max_quantity field is ignored.
  • discount_subtotal_percent - Lowers the price of the total order subtotal by amount percentage. Amount should be a number between 0 and 100. The max_quantity field is ignored.

Create Rules

You have two methods to create the rules used to qualify carts for promotions: match_rules and match_items. The difference between these two is that match_rules applies to cart attributes like the total value or customer group, and match_items applies to attributes of the products in the cart, like SKU or brand.

Both of these use a JSON array that accepts the following data fields:

Key Type Required Details
type String Yes The type of match rule, either group, cart_attribute, cart_item, or cart.
operator String No A logical operator that determines how the match attribute will be compared to the value in the against data field.
match String No The data field of the item indicated by type whose values will be compared with the against value.
against String No The value that the match attribute will be compared against.
children Array No If you indicate that the type for this rule is group, this array should contain the sub-rules that together will be used to match.
match_on String No Indicates whether a cart is considered a match if it satisfies the conditions of “any” child rule or if it must satisfy them “all”.

The top-level rule type must always be group. Matches against carts or products must be set as child rules. You can set rules in both match_rules and match_items to create complex rule sets that do things like apply a discount to a specific product if the total order exceeds a given amount.

In the following examples, we’ll be creating several promotions that use various rules to apply discounts.

Create a Basic Promotion

If you want to use promotions with your store, you will need to create them using the https://api.molt.in/v1/promotions/carts endpoint. By default, new stores contain no promotions. Every promotion that you create must have data for at least the fields marked Required in the table above, though certain promotion types will require other data fields in order to function correctly. You can put data fields in any order.

This example will create a very basic promotion that sets a specific product to a lowered sale price for a period of time. Please note that match_items needs to be passed as a JSON array. On some command-line programs, you will need to use double-quotes for all quotes within the match_items array, as shown below.

curl -X POST https://api.molt.in/v1/promotions/cart \
  -H "Authorization: Bearer XXXX" \
  -d "title=July is coffeemaker month!" \
  -d "from=2015-07-01" \
  -d "to=2015-07-31" \
  -d "status=1" \
  -d "terminating=0" \
  -d "persistent=1" \
  -d "action=discount_to_fixed" \
  -d "amount=29.99" \
  -d "apply_to_shipping=0" \
  -d "customer_uses=1" \
  -d "match_items={ \
    ""type"": ""group"", \
    ""children"": [ \
      { \
        ""type"": ""cart_item"", \
        ""operator"": ""="", \
        ""match_on"": ""any"", \
        ""match"": ""sku"", \
        ""against"": ""1893015"" \
      } \
    ], \
    ""match_on"": ""any""}"

This returns a 201 Created HTML status code (as do all of the other promotion POST actions) the following promotion information:

{
  "status":true,
  "result":
  {
    "id":"1058842448383443104",
    "order":null,
    "created_at":"2015-08-24 19:17:55",
    "updated_at":"2015-08-24 19:17:55",
    "title":"July is coffeemaker month!",
    "from":"2015-07-01",
    "to":"2015-07-31",
    "discount_code":"",
    "max_uses":0,
    "customer_uses":1,
    "customer_group":null,
    "status":
    {
      "value":"Enabled",
      "data":
      {
        "key":"1",
        "value":"Enabled"
      }
    },
    "terminating":
    {
      "value":"No",
      "data":
      {
        "key":"0",
        "value":"No"
      }
    },
    "persistent":
    {
      "value":"Yes",
      "data":
      {
        "key":"1",
        "value":"Yes"
      }
    },
    "action":
    {
      "value":"Discount items to fixed amount",
      "data":
      {
        "key":"discount_to_fixed",
        "value":"Discount items to fixed amount"
      }
    },
    "priority":0,
    "amount":29.99,
    "max_quantity":0,
    "trigger_quantity":0,
    "apply_to_shipping":
    {
      "value":"No",
      "data":
      {
        "key":"0",
        "value":"No"
      }
    },
    "shipping_methods":null,
    "description":"",
    "match_rules":null,
    "match_items":
    {
      "type":"group",
      "children":[
        {
          "type":"cart_item",
          "operator":"=",
          "match_on":"any",
          "match":"sku",
          "against":"1893015"
        }
      ],
      "match_on":"any"
    }
  }
}

Create a Discount Code

You may want to give some discounts only to newsletter subscribers or use them to find out how well your print ads are performing. In these cases, you can apply discounts when the user enters a specific string. These promotions will only be applied to an order if you update the cart with the discount_code data field.

The following cURL statement applies a 15% discount to the first five coffeemakers in the cart.

curl -X POST https://api.molt.in/v1/promotions/cart \
  -H "Authorization: Bearer XXXX" \
  -d "title=August Coffee Monthly Promo" \
  -d "from=2015-08-01" \
  -d "to=2015-09-31" \
  -d "status=1" \
  -d "terminating=1" \
  -d "persistent=1" \
  -d "action=discount_by_percent" \
  -d "amount=15" \
  -d "apply_to_shipping=0" \
  -d "customer_uses=1" \
  -d "max_quantity=5" \
  -d "discount_code=CMONTHLY" \
  -d "customer_uses=1" \
  -d "priority=1" \
  -d "match_items= \
    { \
      ""type"": ""group"", \
      ""children"": \
      [ \
        { \
          ""type"": ""cart_item"", \
          ""operator"": ""="", \
          ""match_on"": ""any"", \
          ""match"": ""sku"", \
          ""against"": ""1893015"" \
        } \
      ], \
      ""match_on"": ""any"" \
    }" \

Create a Free Shipping Promotion

If your store delivers physical objects (as opposed to offering digital downloads or in-store pickup), you can set up a promotion that gives customers free shipping if their order exceeds a set amount. You can even set multiple levels that offer increasingly better shipping options as the order value passes specific benchmarks.

This statement creates a promotion that gives free standard ground shipping to orders over $50.

curl -X POST https://api.molt.in/v1/promotions/cart \
  -H "Authorization: Bearer XXXX" \
  -d "title=Free Ground Shipping" \
  -d "from=2015-01-01" \
  -d "to=2018-12-31" \
  -d "status=1" \
  -d "terminating=0" \
  -d "persistent=1" \
  -d "action=free_ship" \
  -d "apply_to_shipping=1" \
  -d "amount=0" \
  -d "shipping_methods=1059477589212529113" \
  -d "match_rules= \
  { \
    ""type"": ""group"", \
    ""children"": \
    [ \
      { \
        ""type"": ""cart_attribute"", \
        ""operator"": "">"", \
        ""match_on"": ""any"", \
        ""match"": ""value"", \
        ""against"": ""50"" \
      } \
    ], \
    ""match_on"": ""any"" \
  }"

Create a Buy X Get Y Free Promotion

You’re not limited to buy one get one free promotions; you can set any values for the buy and get values. Buy two, get three free; buy 147 get 19 free; any combination of values will work.

The following cURL statement creates a buy two, get one promotion for a specific product.

curl -X POST https://api.molt.in/v1/promotions/cart \
  -H "Authorization: Bearer XXXX" \
  -d "title=Buy 2 Get 1" \
  -d "from=2015-05-01" \
  -d "to=2015-9-31" \
  -d "status=1" \
  -d "terminating=0" \
  -d "persistent=0" \
  -d "action=buy_x_get_y_free" \
  -d "apply_to_shipping=0" \
  -d "trigger_quantity=2" \
  -d "amount=1" \
  -d "customer_uses=2" \
  -d "match_items= \
  { \
    ""type"": ""group"", \
    ""children"": \
    [ \
      { \
        ""type"": ""cart_item"", \
        ""operator"": ""="", \
        ""match_on"": ""any"", \
        ""match"": ""id"", \
        ""against"": ""1044408599557701937"" \
      } \
    ], \
    ""match_on"": ""any"" \
  }"

Create a Customer Discount

Your store may grant employee discounts or preferred customer perks, like free shipping. You can configure these sorts of promotions by matching on customer groups. You will need to create groups and assign them to customers first, of course.

This cURL statement creates an employee discount of 25% off their entire order, so long as the total value is more than $30.

curl -X POST https://api.molt.in/v1/promotions/cart \
  -H "Authorization: Bearer XXXX" \
  -d "title=Employee Discount" \
  -d "from=2015-01-01" \
  -d "to=2018-12-31" \
  -d "status=1" \
  -d "terminating=0" \
  -d "persistent=1" \
  -d "action=discount_subtotal_percent" \
  -d "customer_group=1059506796542034407" \
  -d "apply_to_shipping=1" \
  -d "amount=25" \
  -d "match_rules= \
  { \
    ""type"": ""group"", \
    ""children"": \
    [ \
      { \
        ""type"": ""cart_attribute"", \
        ""operator"": "">"", \
        ""match_on"": ""any"", \
        ""match"": ""value"", \
        ""against"": ""30"" \
      }, \
    ], \
    ""match_on"": ""any"" \
  }"

Retrieve Promotion Information

Once you have created one or more promotions, you have two ways to retrieve that information. The first requires that you know the ID number of the promotion method that you want, and it returns solely the information for that one promotion. The second returns an array of promotions 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 Promotion by ID

You can GET shipping information by adding the specific ID number of the desired method to the promotions/carts endpoint. No additional data fields are required.

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

On success, this returns a 200 OK status code.

Retrieve a List of All Promotions

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

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

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

Search for Promotions by Data Fields

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

curl -X GET https://api.molt.in/v1/promotions/cart/search \
-H "Authorization: Bearer XXXX" \
-d "discount_code=CMONTHLY"

Edit a Promotion

To change one or more values in a single promotion, use a PUT call with the promotions/cart/{ID number} endpoint. You can change most field values through this method, including changing beginning and end dates, match rules, and discount amounts.

curl -X PUT https://api.molt.in/v1/promotions/cart/1058837565450223775 \
  -H "Authorization: Bearer XXXX" \
  -d "to=2015-08-30"

This returns 200 OK and the updated promotion information.

Delete a Single Promotion

To remove a promotion, you use the same promotions/cart/{ID number} endpoint we used to retrieve a single promotion, except we use the DELETE request method.

curl -X DELETE https://api.molt.in/v1/promotions/cart/1058837565450223775 \
  -H "Authorization: Bearer XXXX" \

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

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