Create Promotion

POST Create a Promotion

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

Request

Response

Headers:

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

Body:

Name	Required	Type	Description
type	Required	string	promotion
name	Required	string	A general name for the promotion
description	Required	string	A general description for the promotion
enabled	Required	boolean	true , false
automatic	Optional	boolean	true or false if promotion can be added automatically or require a code. default: false
promotion_type	Required	string	The type of schema being used for the promotion. fixed_discount , percent_discount, x_for_y, x_for_amount , bundle_fixed_discount,
schema	Required	object	Definition of the promotion based on promotion_type. See examples below
min_cart_value	Optional	array	An array of currency-value objects that define a minimum value of a cart required before discount is applied
min_cart_value[].currency	Optional	string	The currency of the minimum cart value threshold
min_cart_value[].amount	Optional	string	The minimum cart value threshold before discount can be applied.
max_discount_value	Optional	array	An array of currency-value objects that define the maximum value of the discount
max_discount_value[].currency	Optional	string	The currency of the maximum discount value
max_discount_value[].amount	Optional	integer	The maximum value of the discount..
start	Required	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	Required	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 Created

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

Percent Discount

X For Y Discount

X For Amount Discount

Fixed Bundle Discount

Item Fixed Discount

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": 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"
  }
}'

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

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

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

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

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

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