Promotions

What’s on this page?

Tulip supports promotions in the form of Automatic Discounts. Retailers can create promotions that are visible to store associates and are applied automatically to an order during checkout.

Priority of a promotion

A numerical value is set for the priority value when creating a new promotion. This value determines the order in which discounts are applied to the cart or items. Promotions with a lower priority value are applied before higher priority value promotions.

External ID for a promotion

An external id is an optional field when creating a promotion. If retailers have their own internal identifier for the promotion being created, it may be put in this field. If left blank, it will create a refnum based on the name of the promotion and use that. The external id must be unique for all promotions and it is not restricted to integers; alphabetic characters are also allowed.

Promotion types

Promotions are discounts that are automatically applied to a cart, during checkout.

These discounts can be of the following types:

Promotion TypeDescription
Line Item DiscountsDiscounts that apply logic to individual line items in an order.

For example, 10% off all items that are in “Category A”.
Order Level DiscountsDiscounts that apply to the whole cart.

For example, 20% off your entire order.
Stacked PromotionsDiscounts are applied to an order one at a time, using priority. Discounts with a lower priority number will be applied before discounts with a higher priority number. Discounts with the same priority may be run in any order that the system decides.

For example, $10 off your order which has priority 1, is applied first, and then 20% off your entire order which has priority 2 is applied next.
Line-Level Promotion BreakdownWhen a discount is applied, Tulip will calculate the proportion of the discount that applies to each line item, regardless of whether or not the discount is an Order Level or Line Item Discount.

For example, if a retailer has a 10% off order level discount for an order with two items where Item A is $10 and the Item B is $20, the app will apply $3 off the entire order, but will also record that $1 of the discount was applied to Line A and $2 of the discount was applied to Line B.
This breakdown is needed by external systems that may need to calculate tax at a line level, for example.

Order of promotions

In order to give the customer the best price, promotions are applied based on the following rules:

  1. Priority – Lowest number is applied first. If multiple promotions have the same priority, the following rules apply
  2. Type – Percentage discounts are applied first, followed by currency.
  3. Amount – Promotions with the largest amounts are applied first.

Note: Because automatic promotions can apply at an item and/or a basket level, that is not taken into account when ordering promotions.

Out of the box Promotion Scripts

Tulip offers a number of out of the box promotion scripts. A discount may be either a Percentage off (%) or an Amount off ($).

Standard Promotions

  • Discount off individual items [Script Name: Simple Item Discount]

    Discount is applied to individual items included in the product selector if the minimums in Value Settings are met.

  • Discount off entire basket [Script Name: Simple Order Discount]

    Discount is applied to the basket if it contains any items included in the product selector and if the minimums in Value Settings are met.

Buy Get

  • BOGO [Script Name: Buy One Get One Discounted]

    Discounts items based on the Script Parameters. This could be Buy one, get one free or Buy two, get one 40% off, etc.

    Script Parameters:

    ParameterDescription
    buy_x_qtyNumber of buy items needed in order to apply discounts to the number of get items
    get_y_qtyNumber of get items that the discount can be applied to for every matched number of buy items
    maximum_number_of_discounted_itemsThe maximum number of items that can be discounted by this script

    Discount is applied to up to get_y_qty items for every buy_x_qty. Both the buy/get items need to be included in the product selector and the minimums in Value Settings need to be met. This discount will only discount maximum_number_of_discounted_items regardless of how many items are in the basket.

    BOGO promotions sort all items in the basket by price. The script iterates through the items and uses the first item (highest price) as the first buy item (or first 3 items if buy_x_qty is set to 3 for example). The next item (or items if get_y_qty is greater than 1) receives the discount. If the maximum_number_of_discounted_items has not been reached and more items are in the basket, this logic is applied to the next items.

Customer Tier Discount

  • Discount for Customers with a specific attribute set to a specific value [Script Name: Order Discount for Customers with specific Attribute]

    Discounts entire order for customers matching the attribute name/value defined in Script Parameters. This could be loyalty_tier: A or subscribe_newsletter: TRUE, etc.

    Script Parameters:

    ParameterDescription
    attribute_nameThe name of the Customer Attribute being checked
    attribute_valueThe value of the Customer Attribute being checked

    Discount is applied to the basket if the selected customer has the attribute_name set attribute_value. The basket must also contain at least one item included in the product selector and the minimums in Value Settings must be met.)

All of the out of the box promotion scripts are defined using the same engine as our Custom Promotion Scripts.

Promotion Config

When applying a promotion, retailers start with a script that serves as a template for the promotion. This template requires a set of configurations for the promotion to be executed.

graph LR A[Promotion Script] --> C; B[Promotion Config] --> C; C[Promotion];

For example, when a retailer would like all orders in their system to have 10% off, they would combine the “X% off” script with promotional configuration. A simplified diagram looks like the following:

graph LR A[Promotion Script:
X% Off] --> C; B[Promotion Config:
X = 10,
start=Jan01-2020,
end=Jan31-2020] --> C; C[Promotion: 10% Off During Jan 2020];

The contents of a promotion config are defined when creating a new promotion. The config includes defining any promotion-specific parameters, as well as a set of “standard parameters” which are needed by all promotions.

Standard Parameters include:

ParameterDefinitionExample
enabledIs this promotion enabled?true / false
startDateTimeThe starting date & time when this promotion is valid2020-01-01 12:00:00
endDateTimeThe ending date & time when this promotion is valid2020-01-01 12:00:00
priorityIn which order should this promotion be applied versus others? Lower numbers are processed before higher numbers. IE Priority 1 is the most important/first one.2
minOrderAmountThe minimum dollar amount required for this promotion to be applied1$50
minItemQtyThe minimum number of items in the basket in order for this promotion to be applied23

Store Specific Promotions

Promotions are assigned to all stores by default. Retailers may optionally choose to select specific stores for this promotion to apply to using the store selector. This can be edited at any time until the promotion expires.

Product Selector

Promotions are able to be applied to any item by default, unless otherwise specified by the promotion script. Using the Product selector, retailers may limit the discount to only apply to a certain category or individual items. If no items are selected, the promotion will not apply to anything .

Using the Product Selector is easy and it is demonstrated in the video below. All you need to do is check the products that you want this discount to apply to. You can select individual variants, or entire products, categories or catalogs. You can even select an entire catalog, then drill down and uncheck a few specific variants.

How To: Add a promotion

  1. Navigate to the admin console.
  2. Go to Checkout > Promotions.
  3. Select Add Promotion, and it will take you to a new page.
  4. Fill in the required fields such as the Name, Priority, along with Start and End Dates.
  5. Input a Percentage Off or Amount Off for the discount
  6. Under the Script Parameters section, from the Promotion Script dropdown, select the type of promotion you would like to add.
  7. (Optional) Select specific store or specific categories/items for this promotion to apply to.
  8. Select Save on the footer.

Custom Promotion Scripts

If a desired promotion isn’t covered by the out of the box promotion strategies, retailers have the ability to write custom scripts that can run arbitrary promotions. Custom promotion scripts use JavaScript. These scripts should be written by someone with technical skills. After creating the custom promotion, the promotion can be reused over and over.

To learn how to write your own custom promotions, refer to Custom Promotion Scripts.

  1. This amount is calculated based on the prices of the items in the basket before any discounts or taxes are applied. This amount takes into account all items in the basket, even if they don’t apply based on other restrictions. The discount will only be applied to items that do apply though, or at the basket level, depending on the specific script. ↩︎

  2. This is based on the total number of items in the basket, regardless of whether the individual items are eligible for the discount. For example, if you have all of the shoes category selected using the product selector, and set this value to 2, this discount will apply if you purchase 2 pairs of shoes, or 1 pair of shoes and 1 dress. (The discount would only apply to the shoes (for an item-level discount) and the dress would be regular price.) ↩︎

← Email Messaging
Store Associate Status →