Create Item Percent Discount Promotion

POST Create Item Percent Discount Promotions

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 to true, a code is autogenerated. If this value is set to 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 item_percent_discount for the percentage discount for item promotions.
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.
max_applications_per_cart	Optional	integer	Specifies the maximum number of application of a promotion per cart.
max_discount_value	Optional	array	Specifies an array of currency-value objects, max_discount_value[].currency and max_discount_value[].amount, that provides the maximum possible discount for the item.
schema	Required	object	Specifies the list of products to include in the promotion and the discount percentage.
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.

The schema object

Name	Required	Type	Description
schema.percent	Required	number	Specifies the discount percentage to be applied to the targeted SKU price. For example 10 is 10% off the product SKU price of $100.
schema.targets	Required	array [string] and string	Specifies the product SKUs or unique identifiers of the products included in the promotion. Set "targets": "all" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define schema.targets, schema.target_nodes or schema.target_attributes, or all three of them to qualify for this promotion.
schema.target_catalogs	Optional	array [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.
schema.target_nodes	Optional	array [string]	Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define schema.target_nodes without defining the schema.targets if the promotion is intended for a certain node. You cannot define "targets": "all" and schema.target_nodes within the same schema. This will result in validation error.
schema.target_attributes[].template	Optional	string	Specifies the name of the template slug to be included in a promotion.
schema.target_attributes[].field	Optional	string	Specifies the unique slug identifier for the field to be included in a promotion.
schema.target_attributes[].type	Optional	string	Specifies the type of the field, such as string, integer, boolean, float, or date.
schema.target_attributes[].value	Optional	Depending on the type of the field, value can be string, integer, boolean, float, or date.	Specifies the value of the field that was specified in the attributes.type. For example, you can specify any color in the value if you indicate color in the attributes.field.
schema.exclude.targets	Optional	array [string]	Specifies the product SKUs to be excluded from the promotion. If targets: "all" is set, you might have to exclude some of the individual SKUs from the promotion.
schema.exclude.nodes	Optional	array [string]	Specifies the unique identifiers of the nodes to be excluded from the promotion. If targets: "all" is set, you might have to exclude some of the nodes from the promotion.
schema.exclude.attributes[].template	Optional	string	Specifies the name of the template slug to be excluded from a promotion.
schema.exclude.attributes[].field	Optional	string	Specifies the unique slug identifier for the field to be excluded from a promotion.
schema.exclude.attributes[].type	Optional	string	Specifies the type of the field, such as string, integer, boolean, float, or date .
schema.exclude.attributes[].value	Optional	Depending on the type of the field, value can be string, integer, boolean, float, or date.	Specifies the value of the field that was specified in the attributes.type. For example, you can specify any color in the value if you indicate color in the attributes.field.

Request Example

curl -X POST 'https://api.moltin.com/v2/promotions' \
     -H "Authorization: Bearer d3233921c41fe6f027dbb09e45f4d11dba015a18' \
     -H 'accept: application/json' \
     -H 'content-type: application/json' \
     -d $'{
       "data": {
         "type": "promotion",
         "name": "Item percent discount promotion example",
         "description": "50% off for SKU1",
         "enabled": true,
         "automatic": false,
         "promotion_type": "item_percent_discount",
         "max_applications_per_cart": 0,
         "schema": {
           "targets" : ["SKU1"],
           "target_nodes" : ["{{nodeId1}}"],
           "target_attributes":[
               {
                   "template": "products(test_template)",
                   "field": "a-color",
                   "type": "string",
                   "value": "white"
               }
           ],
           "exclude": {
               "targets" : ["SKU2"],
               "nodes" : ["{{nodeId}}"],
               "attributes": [
                   {
                     "template": "products(test_template)",
                     "field": "a-color",
                     "type": "string",
                     "value": "blue"
                   }
               ]
           },
           "percent": 50
         },
         "start": "2000-01-01",
         "end": "2100-01-01"
       }
     }

Response Example

201 Created

{
    "data": {
        "type": "promotion",
        "id": "4d5c5d4e-8471-4ffc-ab08-616de59bcc8b",
        "parent_id": "4d5c5d4e-8471-4ffc-ab08-616de59bcc8b",
        "name": "Item percent discount promotion example",
        "description": "50% off for SKU1",
        "enabled": true,
        "current": true,
        "promotion_type": "item_percent_discount",
        "schema": {
            "targets": [
                "SKU1"
            ],
            "percent": 50,
            "target_nodes": [
                "{{nodeId1}}"
            ],
            "target_attributes": [
                {
                    "template": "products(test_template)",
                    "field": "a-color",
                    "type": "string",
                    "value": "white"
                }
            ],
            "exclude": {
                "targets": [
                    "SKU2"
                ],
                "nodes": [
                    "{{nodeId}}"
                ],
                "attributes": [
                    {
                        "template": "products(test_template)",
                        "field": "a-color",
                        "type": "string",
                        "value": "blue"
                    }
                ]
            }
        },
        "start": "2000-01-01T00:00:00Z",
        "end": "2100-01-01T00:00:00Z",
        "created_by": "seller@elasticpath.com",
        "updated_by": "another_seller@elasticpath.com",
        "meta": {
            "timestamps": {
                "created_at": "2022-10-21T13:48:32.665Z",
                "updated_at": "2022-10-21T13:48:32.665Z"
            }
        }
    }
}