Create Free Gift Promotions
POST
Create a Free Gift Promotion
https://api.moltin.com/v2/promotions/
note
Line-item discounts are only supported by the line calculation method. For more information about this method, see the Calculation Method section.
Parameters
Headers
Name | Required | Type | Description |
---|---|---|---|
Authorization | Required | string | The Bearer token required to get access to the API. |
Body
Name | Required | Type | Description |
---|---|---|---|
type | Required | string | Specifies the type of the resource. The type of resource for promotions is, promotion . |
name | Required | string | Specifies a name for the promotion. |
description | Required | string | Specifies a description for the promotion. |
enabled | Required | boolean | Specifies whether the promotion is enabled. The options are true or false , and the default setting is false . |
automatic | Required | boolean | Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is false . When this value is set true , a code is autogenerated. If this value is set false , you must create the code manually. For more information about creating codes, see the Create Promotion Codes section. |
promotion_type | Required | string | Specifies the type of the promotion. Use bundle_gift for free gift promotions. |
max_applications_per_cart | Optional | integer | Specifies the maximum number of application of the promotion per cart. |
min_cart_value | Optional | array | Specifies an array of currency-value objects, min_cart_value[].currency and min_cart_value[].amount , that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. |
schema | Required | object | Specifies the product requirements for the promotion to apply and the free gifts available with the purchase. |
start | Required | string | Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format. For example, "start": "2000-01-01 12:00" . If no time is specified, the default start and end time is set to 00:00 . |
end | Required | string | Specifies the end date and time of the promotion or the end date of the promotion. |
Request Example - Curl
curl -X POST https://api.moltin.com/v2/promotions \
-H "Authorization: Bearer XXXX" \
-H "content-type: application/json" \
--data-raw '{
"data": {
"type": "promotion",
"name": "Buy SKU1 and SKU2 to get free gift",
"description": "SKU1 and SKU2 for free gift",
"enabled": true,
"automatic": true,
"promotion_type": "bundle_gift",
"schema": {
"requirements": [
{
"targets": ["SKU1"], "quantity": 1
},
{
"targets": ["SKU2"], "quantity": 1
}
],
"gifts": ["gift"]
},
"start": "2020-01-01",
"end": "2100-01-01"
}
}'
Response Examples
201 Created
{
"data": {
"type": "promotion",
"id": "bb63a928-6546-42f1-88c8-560b20f5d460",
"name": "Buy Demo to receive free gift",
"description": "Buy Demo to receive free gift",
"enabled": true,
"automatic": true,
"promotion_type": "bundle_gift",
"schema": {
"requirements": [
{
"targets": [
"DEMO"
],
"quantity": 1
}
],
"gifts": [
"gift"
]
},
"start": "2020-01-01T00:00:00Z",
"end": "2100-01-01T00:00:00Z",
"meta": {
"timestamps": {
"created_at": "2021-06-09T17:49:05.291Z",
"updated_at": "2021-06-09T17:49:05.291Z"
}
}
}
}
201 Created
If you add an eligible item for a free gift to the cart, you get a promotion_suggestions
response.
{
"promotion_suggestions": [
{
"promotion_id": "f5a4e0a0-eaf0-4314-8a3c-e40e72f83d1a",
"code": "auto_f5a4e0a0-eaf0-4314-8a3c-e40e72f83d1a",
"info": "free free-gift-001 when my-custom-item is added to cart",
"bundle": [
{
"targets": [
"free-gift-001"
],
"quantity": 1
}
],
"message": "Gift"
}
]
}