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