Composable Frontend 2.0 Learn more 

  • Promotions/
    Promotion Management/
    Create a Cart Fixed Discount Promotion

    Create a Cart Fixed Discount Promotion

    POST Create a cart fixed discount promotion

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

    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 to 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_typeRequiredstringSpecifies the type of the promotion. Use fixed_discount for fixed value cart promotions.
    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. Do not use max_discount_value for this promotion. If you set a maximum discount value for the cart, the max_discount_value overrides the fixed_discount value and the promotion does not work.
    schemaRequiredobjectSpecifies the promotion value, currency, and the products to be excluded from the promotion, if any. See the schema object.
    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

    Promotions are defined by schemas that are used internally to verify promotions and calculate discounts. You must define a schema when you create the promotion. For more information, see the schema.exclude criteria and the targeting fields criteria.

    NameRequiredTypeDescription
    schema.currencies[].currencyRequiredstringSpecifies a three-letter currency code. For example, USD.
    schema.currencies[].amountRequiredintegerSpecifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.
    schema.exclude.targetsOptionalarray [string]Specifies the SKUs of the products to be excluded from the promotion.
    schema.exclude.nodesOptionalarray [string]Specifies the unique identifiers of the nodes to be excluded from the promotion.
    schema.exclude.attributes[].templateOptionalstringSpecifies the name of the template slug to be excluded from a promotion.
    schema.exclude.attributes[].fieldOptionalstringSpecifies the unique slug identifier for the field excluded from a promotion.
    schema.exclude.attributes[].typeOptionalstringSpecifies the type of the field, such as string, integer, boolean, float, or date.
    schema.exclude.attributes[].valueOptionalDepending 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.field. For example, you can specify any color in the value if you indicate color in the attributes.field.
    schema.exclude.conditionsOptionalarray [object]Specifies and/or conditions on nodes and attributes to be excluded from a promotion. For example, if you want to exclude t-shirts and pants that are blue or green in color from a promotion, the items that you wish to exclude should be in node-t-shirts or node-pants and have the color attribute with the value blue or green.
    schema.exclude.conditions.orOptionalarray [object]Specifies or conditions on nodes and attributes to be excluded from a promotion. You can include up to 10 and conditions inside an or array.
    schema.exclude.conditions.or[].andOptionalarray[object]Specifies and conditions on nodes and attributes to be excluded from a promotion. You can only have five items inside an andcondition.
    schema.exclude.conditions.or[].and[].nodeOptionalobjectIncludes values field to specify unique identifiers of the nodes to be excluded from the promotion.
    schema.exclude.conditions.or[].and[].attributeOptionalobjectSpecifies template, field, type, and values of the attribute to be excluded from the promotion.
    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 Example

    curl -X POST https://useast.api.elasticpath.com/v2/promotions \
         -H "Authorization: Bearer XXXX" \
         -H "content-type: application/json" \
        - d $ {
          "data": {
            "type": "promotion",
            "name": "$10 off",
            "description": "$10 off your order!",
            "enabled": true,
            "automatic": false,
            "promotion_type": "fixed_discount",
            "min_cart_value": [
              {
                "amount": 10000,
                "currency": "USD"
              }
            ],
            "schema": {
              "currencies": [
                {
                  "currency": "USD",
                  "amount": 1000
                }
            ],
            "exclude": {
              "targets": [
                "sku1",
                "sku2"
              ],
              "nodes": ["node1"],
              "attributes": [
                 {
                 "template": "products(shoes)",
                 "field": "brand",
                 "type": "string",
                 "value": "adidas"
                 }
              ],
              "conditions": {
                "or": [
                    {
                        "and": [
                            {
                                "node": {
                                    "values": ["3f817e96-2061-4d82-b20a-b840e52c4d7b", "4f817e96-2061-4d82-b20a-b840e52c4d7b"]
                                }
                            },
                            {
                                "attribute": {
                                    "template": "products(shoes)",
                                    "field": "brand",
                                    "type": "string",
                                    "values": ["puma"]
                                }
                            }
                        ]
                    }
                ]
            }
          },
          "target_catalogs": [
            "{{catalogId}}"
          ]
        },
        "start": "2000-01-01",
        "end": "2100-01-01"
      }
    }
    

    Response Example

    201 Created

    {
        "data": {
            "type": "promotion",
            "id": "324f2700-8ece-467f-8a71-2bd892e076a3",
            "parent_id": "324f2700-8ece-467f-8a71-2bd892e076a3",
            "name": "$10 off",
            "description": "$10 off your order!",
            "enabled": true,
            "current": true,
            "promotion_type": "fixed_discount",
            "min_cart_value": [
                {
                    "currency": "USD",
                    "amount": 10000
                }
            ],
            "schema": {
                "currencies": [
                    {
                        "currency": "USD",
                        "amount": 1000
                    }
                ],
                "exclude": {
                    "targets": [
                        "sku1",
                        "sku2"
                    ],
                    "nodes": [
                        "node1"
                    ],
                    "attributes": [
                        {
                            "template": "products(shoes)",
                            "field": "brand",
                            "type": "string",
                            "value": "adidas"
                        }
                    ],
                    "conditions": {
                        "or": [
                            {
                                "and": [
                                    {
                                        "node": {
                                            "values": [
                                                "3f817e96-2061-4d82-b20a-b840e52c4d7b",
                                                "4f817e96-2061-4d82-b20a-b840e52c4d7b"
                                            ]
                                        }
                                    },
                                    {
                                        "attribute": {
                                            "template": "products(shoes)",
                                            "field": "brand",
                                            "type": "string",
                                            "values": [
                                                "puma"
                                            ]
                                        }
                                    }
                                ]
                            }
                        ]
                    }
                },
                "target_catalogs": [
                    "2abfdd78-6a44-4fd1-9b6e-ec0d76378080"
                ]
            },
            "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": "2023-02-02T20:09:31.633Z",
                    "updated_at": "2023-02-02T20:09:31.633Z"
                }
            }
        }
    }
    

    The schema.exclude criteria

    When creating a promotion, you can specify when it should not be applied. The promotion will not be applied on any cart (or cart item, depending on the promotion type) that fulfills at least one of the schema.exclude criteria. The following criteria can be set to exclude items from a promotion:

    • schema.exclude.targets
    • schema.exclude.nodes
    • schema.exclude.attributes
    • schema.exclude.conditions

    For example, if you want to create a promotion with value as SKU1 in schema.exclude.targets and and color yellow and size small in schema.exclude.attributes, then any products with SKU1 or the color yellow or the size small will be excluded from the promotion.

    To exclude products from a promotion based on multiple conditions at the same time, use schema.exclude.conditions. For example, use schema.exclude.conditions to exclude items that are both yellow in color and small in size.

    The targeting fields criteria

    The cart item's catalog is verified if you define the schema.target_catalogs field. If the item is in any of the targeted catalogs specified in schema.target_catalogs, the promotion will be applied. If the item is not in any of the catalogs, the promotion will not be applied.

    Previous
    Promotion Management Overview