Promotions

Promotions allow you to provide discounts to customers. A Promotion can be automatic which will be applied provided any criteria are satisfied, or require codes, which are then used by the end user to get a discount. For more details, see How promotions work.

The Promotion Object

Attributes
Sample Object
Attributes

Name

Type

Description

type

string

promotion

name

string

The name of a promotion

description

string

The description of a promotion

enabled

boolean

Indicates whether a promotion is active

automatic

boolean

Allows promotion to be applied without the need for a code.

promotion_type

string

fixed_discount,percent_discount, x_for_y, x_for_amount

schema

object

Fixed Discount , Percent Discount, X For Y, X For Amount, or Bundle Discount

min_cart_value

array

array of objects

min_cart_value[].currency

string

A currency code

min_cart_value[].amount

integer

The minimum cart value before promotion is applied

max_discount_value

array

array of objects

max_discount_value[].currency

string

A currency code

max_discount_value[].amount

integer

The maximum value of the discount

start

string

The start time of the promotion DateTime

end

string

The end time of the promotion DateTime

Sample Object

Sample with fixed_discount as a promotion_type.

{
"data": {
"type": "promotion",
"id": "15bf00b3-436b-446d-bda9-c021e4e4752b",
"name": "Promo #1",
"description": "Initial Promotion",
"enabled": true,
"promotion_type": "fixed_discount",
"schema": {
"currencies": [
{
"currency": "USD",
"amount": 900
},
{
"currency": "GBP",
"amount": 1100
}
]
},
"start": "2017-05-12T15:04:05Z",
"end": "2019-10-12T15:04:05Z",
"created_at": "2017-11-13T03:00:35.381148442Z",
"updated_at": "2017-11-13T03:00:35.381148514Z"
}
}

The Schema Object

Moltin offers different types of Promotion all defined by a Schema. These Schemas are used internally to verify a Promotion and calculate a discount.

Below is the list of currently available promotion type Schemas - these are to be used in the create promotion request.

Fixed Discount

Fixed discount provides a method to give a fixed discount to a cart.

Attributes
Sample Object
Attributes

Name

Type

Description

currencies

array

An array of objects

currencies[].currency

string

A currency code

currencies[].amount

integer

The amount to discount by

Sample Object
{
"currencies": [
{
"currency": "GBP",
"amount": 1100
}
]
}

Percent Discount

Percent discount provides a method to give a percentage discount to a cart based on the value of cart_items and custom_items.

Attributes
Sample Object
Attributes

Name

Type

Description

currencies

array

An array of objects

currencies[].currency

string

A currency code

currencies[].percentage

float

The percentage to discount by

Sample Object
{
"currencies": [
{
"currency": "GBP",
"percentage": 12.5
}
]
}

X for Y

An X for Y discount allows items of the same product to be sold on a 2 for 1 or 3 for 2 (or any other combination) basis.

Attributes
Sample Object
Attributes

Name

Type

Description

x

integer

Number of items required to activate promotion.

y

integer

Number of items that will be used to calculate the total charge.

targets

array

Array of strings

targets[]

string

A list of strings that represent the productIDs and/or SKUs.

Sample Object
{
"data": {
"type": "promotion",
"promotion_type": "x_for_y",
"name": "X for Y Promotion Example",
"description": "Example description for X for Y promotion.",
"enabled": true,
"automatic": true,
"schema":{
"x": 3,
"y": 2,
"targets": ["SKU-1", "SKU-2"]
},
"start":"2020-01-01",
"end":"2030-01-01"
}
}

Multiples will be honoured by applying a multiple of the discount, e.g. 3 for 2 with 6 of the targeted items in a cart would yield a discount value equal to the value of 2 items.

X for Amount

An X for Amount discount allows items of the same product to be sold on a X for fixed amount basis. e.g. 2 for $10 or 4 for $20.

Attributes
Sample Object
Attributes

Name

Type

Description

x

integer

Number of items required to activate promotion.

currencies

array

Array of objects

currencies[].currency

string

A currency code

currencies[].amount

integer

The amount to vend items for.

Sample Object
{
"data": {
"type": "promotion",
"name": "BF",
"description": "Black Friday",
"enabled": true,
"automatic": true,
"promotion_type": "x_for_amount",
"schema": {
"x": 3,
"currencies": [
{"currency": "USD", "amount": 500}
],
"targets": ["SKU-1","SKU-2"]
},
"start": "2020-01-01",
"end": "2030-01-01"
}
}

Bundle Discount

A bundle discount can be used to provide a fixed price for a selection of products when bought together. E.g. buy product x, y & z for $15 or buy 2 of product x and 3 of product y or z for $25

Attributes
Sample Object
Attributes

Name

Type

Description

requirements

array

Array of objects

requirements[].targets

array

Array of strings

requirements[].targets[]

string

A list of strings that represent the productIDs and/or SKUs.

requirements[].quantity

integer

The require number of corresponding target to satisfy the promotion.

currencies

array

Array of objects.

currencies[].currency

string

A currency code.

currencies[].amount

integer

The amount to vend items for.

Sample Object
{
"data": {
"type": "promotion",
"name": "BF",
"description": "Black Friday",
"enabled": true,
"automatic": true,
"promotion_type": "bundle_fixed_discount",
"schema": {
"requirements": [
{"targets":["prodID-1", "SKU-1", "prodID-2", "SKU-3"], "quantity": 1},
{"targets":["prodID-4", "SKU-5"], "quantity": 2},
{"targets":["prodID-12", "SKU-11"], "quantity": 1}
],
"currencies": [
{"currency": "GBP", "amount": 2500},
{"currency": "USD", "amount": 2400}
]
},
"start": "2020-01-01",
"end": "2030-01-01"
}
}

The Promotion Code Object

A promotion code is represented by the following, very simple, object.

Attributes
Sample Object
Attributes

Name

Type

Description

code

string

Any string

uses

integer

Limit for number of times this code can be used

user

string

A string used as an identifier relating to a user

Sample Object
{
"code":"ZXY_CBA",
"uses": 5,
"user": "qwertyuiop"
}