Create Promotion

Create a Promotion

POST https://api.moltin.com/v2/promotions

Headers

Name	Type	Description
Authorization	string	The Bearer token to grant access to the API.

Request Body

Name	Type	Description
type	string	promotion
name	string	A general name for the promotion
description	string	A general description for the promotion
enabled	boolean	true , false
automatic	boolean	true or false if promotion can be added automatically or require a code. default: false
promotion_type	string	The type of schema being used for the promotion. fixed_discount , percent_discount, x_for_y, x_for_amount , bundle_fixed_discount,
schema	object	Definition of the promotion based on promotion_type. See examples below
min_cart_value	array	An array of currency-value objects that define a minimum value of a cart required before discount is applied
min_cart_value[].currency	string	The currency of the minimum cart value threshold
min_cart_value[].amount	string	The minimum cart value threshold before discount can be applied.
max_discount_value	array	An array of currency-value objects that define the maximum value of the discount
max_discount_value[].currency	string	The currency of the maximum discount value
max_discount_value[].amount	integer	The maximum value of the discount..
start	string	The start time of the promotion datetime (yyyy-mm-dd, yyyy-mm-ddThh:mm:ss+hh:mm). The simpler format will start the promotion at 00:00 UTC of the datetime specified. If time is not specified, it will default to the time at which the request was created.
end	string	The end time of the promotion datetime (yyyy-mm-dd, yyyy-mm-ddThh:mm:ss+hh:mm). The simpler format will start the promotion at 00:00 UTC. If time's not provided, it will default to the time at which the request was created.

201

{
  "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"
  }
}

Example Request Payloads

Fixed Discount

curl -X "POST" "https://api.moltin.com/v2/promotions" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: 1af41d46cb18d11b3abffb66c3cb20944d3452e7' \
     -d $'{
  "data": {
    "type": "promotion",
    "name": "BF",
    "description": "Black Friday",
    "enabled": true,
    "automatic": false,
    "promotion_type": "fixed_discount",
    "schema": {
      "currencies": [
        {
          "currency": "GBP",
          "amount": 10
        },
        {
          "currency": "USD",
          "amount": 10
        }
      ]
    },
    "min_cart_value": [
      {
        "currency": "GBP",
        "amount": 20000
      },
      {
        "currency":"USD",
        "amount": 19000
      }
    ],
    "end": "2018-06-12",
    "start": "2017-05-12"
  }
}'

Percent Discount

curl -X "POST" "https://api.moltin.com/v2/promotions" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: 1af41d46cb18d11b3abffb66c3cb20944d3452e7' \
     -d $'{
  "data": {
    "type": "promotion",
    "name": "BF",
    "description": "Black Friday",
    "enabled": true,
    "automatic": true,
    "promotion_type": "percent_discount",
    "schema": {
      "currencies": [
        {
          "currency": "USD",
          "percentage": 10
        }
      ]
    },
    "min_cart_value": [
      {
        "currency": "GBP",
        "amount": 20000
      },
      {
        "currency":"USD",
        "amount": 19000
      }
    ],
    "start": "2017-05-12T15:04:05+00:00",
    "end": "2018-06-12T15:04:05+00:00"
  }
}'

X For Y Discount

curl -X "POST" "https://api.moltin.com/v2/promotions" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: 1af41d46cb18d11b3abffb66c3cb20944d3452e7' \
     -d $'{
  "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"
  }
}

X For Amount Discount

curl -X "POST" "https://api.moltin.com/v2/promotions" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: 1af41d46cb18d11b3abffb66c3cb20944d3452e7' \
     -d $'{
  "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"
  }
}

Fixed Bundle Discount

curl -X "POST" "https://api.moltin.com/v2/promotions" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: 1af41d46cb18d11b3abffb66c3cb20944d3452e7' \
     -d $'{
  "data": {
    "type": "promotion",
    "name": "BF",
    "description": "Black Friday",
    "enabled": true,
    "automatic": false,
    "promotion_type": "bundle_fixed_discount",
    "schema": {
      "requirements":[
        {"targets":["prod1","prodX"],"quantity": 2},
        {"targets":["prod3","prodW"],"quantity": 1},
      ],
      "currencies": [
        {
          "currency": "GBP",
          "amount": 10
        },
        {
          "currency": "USD",
          "amount": 10
        }
      ]
    },
    "min_cart_value": [
      {
        "currency": "GBP",
        "amount": 20000
      },
      {
        "currency":"USD",
        "amount": 19000
      }
    ],
    "end": "2021-06-12",
    "start": "2017-05-12"
  }
}'

Item Fixed Discount

curl -X "POST" "https://api.moltin.com/v2/promotions" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: 1af41d46cb18d11b3abffb66c3cb20944d3452e7' \
     -d $'{
  "data": {
    "type": "promotion",
    "name": "BF",
    "description": "Black Friday",
    "enabled": true,
    "automatic": false,
    "promotion_type": "item_fixed_discount",
    "schema": {
      "targets":["prod1","prodX"],
      "currencies": [
        {
          "currency": "GBP",
          "amount": 10
        },
        {
          "currency": "USD",
          "amount": 10
        }
      ]
    },
    "min_cart_value": [
      {
        "currency": "GBP",
        "amount": 20000
      },
      {
        "currency":"USD",
        "amount": 19000
      }
    ],
    "end": "2018-06-12",
    "start": "2017-05-12"
  }
}'

Item Percent Discount

curl -X "POST" "https://api.moltin.com/v2/promotions" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: 1af41d46cb18d11b3abffb66c3cb20944d3452e7' \
     -d $'{
  "data": {
    "type": "promotion",
    "name": "BF",
    "description": "Black Friday",
    "enabled": true,
    "automatic": true,
    "promotion_type": "item_percent_discount",
    "schema": {
      "targets":["prod1","prodX"],
      "percent":25.0
    },
    "min_cart_value": [
      {
        "currency": "GBP",
        "amount": 20000
      },
      {
        "currency":"USD",
        "amount": 19000
      }
    ],
    "start": "2017-05-12T15:04:05+00:00",
    "end": "2028-06-12T15:04:05+00:00"
  }
}'