Set Promotions

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
  }
}

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
  }
}

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

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

Another optional field to add a description for your promotion.

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.

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.

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.

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

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.