Skip to content

Latest commit

 

History

History
380 lines (349 loc) · 9.71 KB

create-promotion.md

File metadata and controls

380 lines (349 loc) · 9.71 KB

Create Promotion

{% api-method method="post" host="https://api.moltin.com" path="/v2/promotions" %} {% api-method-summary %} Create a Promotion {% endapi-method-summary %}

{% api-method-description %}

{% endapi-method-description %}

{% api-method-spec %} {% api-method-request %} {% api-method-headers %} {% api-method-parameter name="Authorization" type="string" required=true %} The Bearer token to grant access to the API. {% endapi-method-parameter %} {% endapi-method-headers %}

{% api-method-body-parameters %} {% api-method-parameter name="type" type="string" required=true %} promotion {% endapi-method-parameter %}

{% api-method-parameter name="name" type="string" required=true %} A general name for the promotion {% endapi-method-parameter %}

{% api-method-parameter name="description" type="string" required=true %} A general description for the promotion {% endapi-method-parameter %}

{% api-method-parameter name="enabled" type="boolean" required=true %} true , false {% endapi-method-parameter %}

{% api-method-parameter name="automatic" type="boolean" required=false %} true or false if promotion can be added automatically or require a code. default: false {% endapi-method-parameter %}

{% api-method-parameter name="promotion_type" type="string" required=true %} The type of schema being used for the promotion. fixed_discount , percent_discount, x_for_y, x_for_amount , bundle_fixed_discount, {% endapi-method-parameter %}

{% api-method-parameter name="schema" type="object" required=true %} Definition of the promotion based on promotion_type. See examples below {% endapi-method-parameter %}

{% api-method-parameter name="min_cart_value" type="array" required=false %} An array of currency-value objects that define a minimum value of a cart required before discount is applied {% endapi-method-parameter %}

{% api-method-parameter name="min_cart_value[].currency" type="string" required=false %} The currency of the minimum cart value threshold {% endapi-method-parameter %}

{% api-method-parameter name="min_cart_value[].amount" type="string" required=false %} The minimum cart value threshold before discount can be applied. {% endapi-method-parameter %}

{% api-method-parameter name="max_discount_value" type="array" required=false %} An array of currency-value objects that define the maximum value of the discount {% endapi-method-parameter %}

{% api-method-parameter name="max_discount_value[].currency" type="string" required=false %} The currency of the maximum discount value {% endapi-method-parameter %}

{% api-method-parameter name="max_discount_value[].amount" type="integer" required=false %} The maximum value of the discount.. {% endapi-method-parameter %}

{% api-method-parameter name="start" type="string" required=true %} 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. {% endapi-method-parameter %}

{% api-method-parameter name="end" type="string" required=true %} 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. {% endapi-method-parameter %} {% endapi-method-body-parameters %} {% endapi-method-request %}

{% api-method-response %} {% api-method-response-example httpCode=201 %} {% api-method-response-example-description %}

{% endapi-method-response-example-description %}

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

{% endapi-method-response-example %} {% endapi-method-response %} {% endapi-method-spec %} {% endapi-method %}

Example Request Payloads

{% tabs %} {% tab title="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"
  }
}'

{% endtab %}

{% tab title="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"
  }
}'

{% endtab %}

{% tab title="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"
  }
}

{% endtab %}

{% tab title="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"
  }
}

{% endtab %}

{% tab title="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"
  }
}'

{% endtab %}

{% tab title="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"
  }
}'

{% endtab %}

{% tab title="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"
  }
}'

{% endtab %} {% endtabs %}