Skip to main content

Promotions API

This guide covers how to create and manage promotions programmatically, including webhooks and common integration patterns.

Creating a Promotion​

Use promotionCreate to create a promotion.

mutation promotionCreate($input: PromotionCreateInput!) {
  promotionCreate(input: $input) {
    promotion {
      id
      name
      type
      startDate
      endDate
    }
  }
}

Creating Promotion Rules​

Use promotionRuleCreate to add rules to a promotion.

Catalogue Promotion Rule​

mutation promotionRuleCreate($input: PromotionRuleCreateInput!) {
  promotionRuleCreate(input: $input) {
    promotionRule {
      id
      name
      rewardValueType
      rewardValue
      cataloguePredicate
    }
  }
}

Order Promotion Rule (Subtotal Discount)​

mutation promotionRuleCreate($input: PromotionRuleCreateInput!) {
  promotionRuleCreate(input: $input) {
    promotionRule {
      id
      name
      rewardValueType
      rewardValue
      rewardType
      orderPredicate
    }
  }
}

Order Promotion Rule (Gift)​

{
  "input": {
    "name": "Free gift on orders over $100",
    "promotion": "UHJvbW90aW9uOjEyMzA0YmM4LTA2ZTMtNDg1Mi05ODU1LWM4ZDkyMDgzNTYwZA==",
    "channels": ["Q2hhbm5lbDoy"],
    "rewardType": "GIFT",
    "orderPredicate": {
      "discountedObjectPredicate": {
        "baseSubtotalPrice": {
          "range": { "gte": 100 }
        }
      }
    },
    "gifts": ["UHJvZHVjdFZhcmlhbnQ6MzQ4", "UHJvZHVjdFZhcmlhbnQ6NDAw"]
  }
}

Channel Availability​

Rules require channel assignments to apply. When using FIXED reward value type, all assigned channels must share the same currency.

Promotion Events​

Track promotion changes through the events API:

query Promotion($id: ID!) {
  promotion(id: $id) {
    events {
      ... on PromotionEventInterface {
        type
        date
        createdBy {
          ... on User {
            id
          }
        }
      }
      ... on PromotionRuleEventInterface {
        ruleId
      }
    }
  }
}

Event types include:

  • PROMOTION_CREATED
  • PROMOTION_UPDATED
  • PROMOTION_STARTED
  • PROMOTION_ENDED
  • RULE_CREATED
  • RULE_UPDATED
  • RULE_DELETED

See PromotionEventsEnum for the full list.

Webhooks​

Subscribe to promotion-related webhooks to sync promotions with external systems:

WebhookTrigger
PROMOTION_CREATEDNew promotion created
PROMOTION_UPDATEDPromotion details changed
PROMOTION_DELETEDPromotion removed
PROMOTION_STARTEDPromotion became active (start date reached)
PROMOTION_ENDEDPromotion expired (end date reached)
PROMOTION_RULE_CREATEDNew rule added
PROMOTION_RULE_UPDATEDRule modified
PROMOTION_RULE_DELETEDRule removed

Common Integration Patterns​

Promotion Duration Display​

Build an app to show remaining promotion time to customers:

query PromotionDuration($id: ID!) {
  promotion(id: $id) {
    name
    startDate
    endDate
  }
}

Calculate and display countdown timers based on endDate.

Sync with Marketing Platforms​

Use webhooks to sync promotion data with email marketing or advertising platforms:

  1. Subscribe to PROMOTION_STARTED and PROMOTION_ENDED
  2. When a promotion starts, trigger marketing campaigns
  3. When it ends, pause or update campaigns

Inventory-Based Promotions​

Build automation to:

  1. Monitor inventory levels
  2. Create promotions for overstocked items
  3. End promotions when inventory normalizes

Price Recalculation​

Catalogue promotion prices are calculated asynchronously. After creating or modifying a catalogue promotion:

  • Prices won't update immediately
  • A background task processes the changes
  • Subscribe to relevant webhooks to know when recalculation completes

Expired Promotions in checkout​

To Do: VERIFY When a promotion expires while products are in a customer's checkout:

  1. Catalogue promotions: The discounted price remains unchanged for 1 hour (default setting for CHECKOUT_PRICES_TTL) the the next checkout refresh or mutation that affect discounted line.
  2. Order promotions: The discount is removed when the checkout is updated.

Permissions​

All promotion operations require MANAGE_DISCOUNTS permission.