Composable Frontend 2.0 Learn more 

  • Promotions/
    Promotion Management/
    Create a Free Gift Promotion

    Create Free Gift Promotions

    POST Create a Free Gift Promotion

    https://useast.api.elasticpath.com/v2/promotions/
    

    • Line-item discounts are only supported by the line calculation method. For more information about this method, see the Calculation Method section. Hierarchy-based promotions are not supported for free gift promotion.
    • We recommend using auto_add_free_gift featrure with automatic setting enabled. When automatic is set to true, it indicates that promotions are added automatically, and discounts are applied accordingly. If you enable the auto_add_free_gift, but do not enable the automatic setting, gift items will be added without discounts. In this case, shoppers need to apply coupon codes twice, first to add the gift item and then to apply the discount.

    Parameters

    Headers

    NameRequiredTypeDescription
    AuthorizationRequiredstringThe Bearer token required to get access to the API.

    Body

    NameRequiredTypeDescription
    typeRequiredstringSpecifies the type of the resource. The type of resource for promotions is, promotion.
    nameRequiredstringSpecifies a name for the promotion.
    descriptionRequiredstringSpecifies a description for the promotion.
    enabledRequiredbooleanSpecifies whether the promotion is enabled. The options are true or false, and the default setting is false.
    automaticRequiredbooleanSpecifies 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_typeRequiredstringSpecifies the type of the promotion. Use bundle_gift for free gift promotions.
    max_applications_per_cartOptionalintegerSpecifies the maximum number of application of the promotion per cart.
    min_cart_valueOptionalarraySpecifies 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.
    schemaRequiredobjectSpecifies the product requirements for the promotion to apply and the free gifts available with the purchase.
    startRequiredstringSpecifies 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.
    endRequiredstringSpecifies the end date and time of the promotion or the end date of the promotion.

    The schema object

    NameRequiredTypeDescription
    schema.requirements.targetsRequiredarray [string]Specifies the product IDs or SKUs to be applied for the promotion. For example, for requirements: [{quantity: 1, targets: ["a", "b"]}, {quantity: 1, targets: ["c", "d"]}], means this promotion requires one of either SKU a or b and one of either SKU c or d in the cart to qualify for the free gift promotion.
    schema.requirements.quantityRequiredintegerSpecifies the quantities of products to be applied for the promotion.
    schema.giftsRequiredarray [string]Specifies all the gift items that a user can avail when the user qualifies for the promotion. The gift quantity applies to each specified item. For example, if the promotion includes giftA and giftB, user can avail both the gifts if the cart qualifies for the gift promotion. If the cart qualifies for two gift promotions, the user can use two giftA and two giftB.
    schema.auto_add_free_giftOptionalbooleanWhen set to true, free gift items are automatically added to the shopping cart for all the eligible products. Default is false.
    schema.target_catalogsOptionalarray [string]Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.

    Request Examples

    curl -X POST https://useast.api.elasticpath.com/v2/promotions \
         -H "Authorization: Bearer XXXX" \
         -H "content-type: application/json" \
         -d $ {
            "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",
                "max_applications_per_cart": 0,
                "schema": {
                    "requirements": [
                    {
                        "targets": [
                            "SKU1"
                    ],
                        "quantity": 1
                    },
                    {
                        "targets": [
                            "SKU2"
                    ],
                        "quantity": 1
                        }
                    ],
                    "gifts": [
                        "gift"
                    ],
                    "target_catalogs": [
                        "{{catalogId}}"
                    ],
                    "auto_add_free_gift": true
                    },
                "start": "2020-01-01",
                 "end": "2100-01-01"
      }
    }
    

    Response Examples

    201 Created

    {
        "data": {
            "type": "promotion",
            "id": "3e84c3ac-df96-4ef8-aae4-f3241a1f3b2e",
            "parent_id": "3e84c3ac-df96-4ef8-aae4-f3241a1f3b2e",
            "name": "Buy SKU1 and SKU2 to get free gift",
            "description": "SKU1 and SKU2 for free gift",
            "enabled": true,
            "current": true,
            "automatic": true,
            "promotion_type": "bundle_gift",
            "schema": {
                "requirements": [
                    {
                        "targets": [
                            "SKU1"
                        ],
                        "quantity": 1
                    },
                    {
                        "targets": [
                            "SKU2"
                        ],
                        "quantity": 1
                    }
                ],
                "gifts": [
                    "gift"
                ],
                "target_catalogs": [
                    "2abfdd78-6a44-4fd1-9b6e-ec0d76378080"
                ],
                "auto_add_free_gift": true
            },
            "start": "2020-01-01T00:00:00Z",
            "end": "2100-01-01T00:00:00Z",
            "meta": {
                "timestamps": {
                    "created_at": "2023-09-22T16:28:04.168Z",
                    "updated_at": "2023-09-22T16:28:04.168Z"
                }
            }
        }
    }
    
    Previous
    Create Item Percent Discount Promotions