Blog • Carts | Promotions

How promotions work

Last updated: 26 Jun 2019

Promotions allow you to provide discounts to customers. By defining a Promotion and a code, you put in place the facility to offer discounts to customers applied directly to their shopping carts.

The promotions you create require codes to be attached to them. These codes are subsequently used by customers to apply promotions directly to carts and provide the stipulated discount. It is up to you to decide how you wish to distribute the codes to your customers; however, feel free to check out our UI example below.

Set up a promotion in two simple steps:

  1. Create a promotion.
  2. Add promotion codes to the promotion ID.

At the cart level, promotion works in the following way:

  • Products are added to a cart, and if promotion is applicable, the user will input a promotion code to apply discount price.
  • The cart is checked out with the promotion applied.

Get your access token

You will need to get a client_credentials access token to follow along making the API requests outlined below.

curl -X POST https://api.moltin.com/oauth/access_token \
     -d "client_id=XXXX" \
     -d "client_secret=XXXX" \
     -d "grant_type=client_credentials"

Create a Promotion

The promotion is defined by the following:

  • Name and description. Helps you identify the promotion
  • Start and end date. Defines when the Promotion starts and finishes. If the dates are not a match, the Promotion response returns a 404 not found.
  • Enabled. Allows you to switch the promotion on/off without having to touch the start/end times.
  • Promotion type. Typically, a percentage taken off the original price or a fixed amount applied instead. To see a full list of supported promotion_types visit the API docs.
  • Schema. The value and currency applied to your promotion. This depends on the promotion_types, e.g. if fixed_discount the value defined will be applied instead of the original price, if percentage_discount, the original price will be decreased by the defined percent.
curl -X POST https://api.moltin.com/v2/promotions \
     -H "Authorization: Bearer XXXX" \
     -d $'{
      "data": {
        "type": "promotion",
        "id": "c12ddfe7-3478-4822-b339-4a68ee9926a6",
        "name": "Coolpromo",
        "description": "Promotion",
        "enabled": true,
        "promotion_type": "percent_discount",
        "schema": {
          "currencies": [
        {
            "currency": "USD",
            "percentage": 10
            },
        {
            "currency": "GBP",
            "percentage": 10
            }
          ]
        },
        "start": "2017-01-13T00:00:00Z",
        "end": "2018-01-13T00:00:00Z",
        "created_at": "2018-05-29T20:02:57.238736345Z",
        "updated_at": "2019-05-29T20:02:57.238736906Z"
      }
  }'

Tie promotion code(s) to the Promotion

A promotion is located and applied through a code. Each Promotion can have unlimited number of codes.

Please note that codes will be automatically removed from a promotion once the promotion expires.

The code is the one your customers will enter after they have added the items to their cart.

How to handle codes

Use user-friendly code formatting in a scenario where you wish your customers to use the same code for a limited period of time, such as Holiday season, e.g. 20%-OFF.

Use unique codes in a scenario where you would like to control the number of products covered by the promotion.

curl -X POST https://api.moltin.com/v2/promotions/:id/codes \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
      "data":{
        "type":"promotion_codes",
        "codes": [
          {"code":"SAVE10%"},
          {"code":"CoolPromo"}
        ]
      }
    }'

Use a Promotion

Once you have a promotion and code(s) applied to it, you can then update your code so it works at the cart level for when you want your customers to apply it to their cart items.

Add Item(s) to a Cart

The customer must have items already added to their cart before a promotion can be applied.

The products added to cart must be in the same currency as the promotion currencies set up.

curl -X POST https://api.moltin.com/v2/carts/:reference/items \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
      "data": {
          "id": "df32387b-6ce6-4802-9b90-1126a5c5a54f",
          "type": "cart_item",
          "quantity": 1
        }
      }'

Apply the Promotion

The promotion codes work with the Cart endpoint. The customer will input one of the promotion codes, and then you will need to make an API call to apply the pre set-up promotion the codes are tied to.

User Interface example:

 

curl -X POST https://api.moltin.com/v2/carts/:cartId/items \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
       "data": {
         "type": "promotion_item",
         "code": "SAVE10%"
       }
     }'

Checkout with updated cart

Once the promotion has been applied to the cart, the order is ready to be processed.

curl -X POST https://api.moltin.com/v2/carts/:reference/checkout \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
       "data": {
         "customer": {
           "email": "john@moltin.com",
           "name": "John Doe"
         },
         "billing_address": {
           "first_name": "John",
           "last_name": "Doe",
           "company_name": "Moltin",
           "line_1": "2nd Floor British India House",
           "line_2": "15 Carliol Square",
           "city": "Newcastle upon Tyne",
           "postcode": "NE1 6UF",
           "county": "Tyne & Wear",
           "country": "UK"
         },
         "shipping_address": {
           "first_name": "John",
           "last_name": "Doe",
           "company_name": "Moltin",
           "phone_number": "(555) 555-1234",
           "line_1": "2nd Floor British India House",
           "line_2": "15 Carliol Square",
           "city": "Newcastle upon Tyne",
           "postcode": "NE1 6UF",
           "county": "Tyne & Wear",
           "country": "UK",
           "instructions": "Leave in porch"
         }
       }
    }'

How promotions are applied

Promotions are applied to a cart using a simple strategy. Your promotions will appear as cart items in your cart with negative values. The summation of cart items will simply subtract any promotion amount from the sub-total.

Next steps

Once a Cart has been converted to an Order using either of the methods above, you will most likely want to capture payment for order.