More in Learn

Set Promotions

You can now set Promotions in Crystallize via the Shop API. To learn more about what a promotion entails, you can visit the concepts section that explains it further. Note that you can also set up promotions in the Crystallize App itself.

Example Mutation

Let’s start off with looking at a mutation, followed by going deeper into each of the fields in the mutation:

mutation CreatePromotion {
setPromotions(
input: {
identifier: "summer_sale_2024"
name: "Summer Sale 2024"
description: "Get amazing discounts on summer essentials!"
periods: [
{ start: "2024-06-01T00:00:00Z", end: "2024-08-31T23:59:59Z" }
]
triggers: {
minValue: 50.00
customerGroups: ["crystal_customers"]
}
targets: {
topics: ["summer_wear"]
exclusions: { skus: ["beach-shorts-blue", "beach-shorts-white"] }
}
limitations: {
maxUsage: 1000
maxUsagePerCustomer: 2
cumulativeDiscount: false
repeatable: true
}
mechanism: {
type: Percentage
value: 20.0
}
}
) {
identifier
name
description
# Add other fields you want to return after creation
}
}

Identifier

Required field to specify the identifier of the promotion in Crystallize.

Name

This is an optional field for providing the name of the promotion.

Description

Another optional field to add a description for your promotion.

Periods

An array of periods a promotion should be valid for. Has two fields within it:

  • start: A date time string.
  • end: A date time string.

If unspecified, the promotion will take effect immediately and is permanent until modified or deleted.

Mechanism

A mechanism is there for you to specify the type of discount you would like to apply. It takes in two values: type and value. Value is always a floating point number but type can be one of the following:

  • percentage: A percentage value.
  • fixed: A fixed amount as a discount.
  • DynamicFixed: For when you want the discount amount to be based on new set price.
  • XForY: Buy X for the price of Y. If items in the cart have different prices, then the cheapest one(s) will be discounted.

Triggers

This is a list of conditions that will trigger the promotion to be applied to a cart. It can be one or more of the following:

  • skus: An array of stock-keeping units (SKUs).
  • topics: If an item contains any of the topics provided to this array.
  • paths: An array of item paths.
  • productIds: An array of product IDs.
  • minValue: A float value for the minimum value of the cart.
  • minQuantity: This is an integer you can provide to specify the minimum quantity in the cart.
  • currencies: An array for currencies. For example, if you have a multi-currency shop, only trigger the promotion for Euros or Dollars.
  • markets: You can create specific segments in Crystallize that are called markets. This field takes an array of market identifiers.
  • customers: This is for when you want to trigger a promotion based on the customer. It takes in a list of customer identifiers.
  • customerGroups: You can have customer groups assigned to your customers. This field takes in a list of customer groups. Example: when you have customer levels based on loyalty points earned.
  • codes: An array of codes, that if present in the cart would lead to triggering a discount. Use case for voucher-based discounts.
  • xForY: Configuration for "Buy X, Pay for Y" deals.
  • exclusions: Exclusion contains a list of fields where you can exclude certain items from the promotion based on SKUs, paths, productIds, topics, markets, customers. etc.

Targets

You have triggers to specify conditions for when a promotion is to be applied. Targets are there to know which item(s) the promotion should be applied to. It shares some similar fields with triggers such as:

  • skus
  • paths
  • productIds
  • topics
  • exclusions

Limitations

You might want to add some limitations to your promotions, and that is exactly what the limitations field does. You can have limitations based on the following:

  • canBeCombinedWith: An array of other discounts the promotion can be combined with.
  • maxUsage: An integer value stating how many times a discount can be applied.
  • maxUsagePerCustomer: Similar to maxUsage, but this time you define maximum usage per customer.
  • cumulativeDiscount: A boolean value to decide whether or not a discount can be applied in addition to other discounts.
  • quantityPerTrigger: An integer value to specify the number of times a discount can be applied per trigger.
  • repeatable: Takes in a boolean value to determine whether the discount should be repeated in the cart, or if it should be applied only once.

Check Out Our Promotions Livestream

People showing thumbs up

Need further help?

Join and ask our
slack community.

Join our slack community