1. Integrations

Promotion integration: calculating custom discounts

This guide explains how to use promotion integration with integration events to handle scenarios beyond the Rules Engine's capabilities.

Complex promotion scenarios

Rules Engine limitations

While the Rules Engine is powerful, some promotion scenarios require more complex calculations than expressions can handle.

Example scenario

Consider this promotion: "Buy 2 from Category A, Get 2 from Category B for 50% off" with these requirements:

  1. Quantity scaling

    • Discount increases with quantity
    • Maintains promotion ratios

  2. Split quantities

    • Quantities divided across items
    • Maintains category relationships

  3. Price optimization

    • Applies to least expensive items first
    • Maximizes customer benefit

This scenario requires custom code implementation through promotion integration.

Implementation workflow

Process overview

  1. Create promotion with null ValueExpression
  2. OrderCloud calls middleware when promotion applies
  3. Middleware calculates discount values
  4. OrderCloud applies calculated discounts

Key features

  • Maintains EligibleExpression evaluation
  • Supports auto-applied promotions
  • Works alongside standard promotions

Best practices

  • Use standard promotions when possible
  • Reserve integration for complex scenarios
  • Consider performance implications

Configuration properties

UseIntegration property

  • Type: Boolean
  • Default: false
  • Purpose: Enables middleware integration
  • Behavior: Triggers integration event calls

PromotionIntegration resource

Resource definition

json
{
  "Url": "",
  "HashKey": ""
}

Implementation notes

  • One integration per marketplace
  • Requires valid endpoint URL
  • Includes security hash key

Integration payloads

Request payload

json
{
  "Environment": "",
  "Order": {},
  "LineItems": [],
  "PromosApplied": [],
  "PromosRequested": []
}

Payload components

  • Environment: Identifies source (Production/Staging/Sandbox)
  • Order: Complete order object
  • LineItems: All order line items
  • PromosApplied: Currently applied promotions
  • PromosRequested: Promotions pending application

Response payload

json
{
  "PromosAccepted": [],
  "PromosRejected": []
}

Accepted promotion format

json
{
  "ID": "",
  "LineItemID": "",  // null if order level promotion
  "Amount": 0
}

Rejected promotion format

json
{
  "ID": "",
  "LineItemID": "",  // null if order level promotion
  "Reason": ""
}

API endpoints

Configuration management

  • GET v1/integrations/promotion: Retrieve settings
  • PUT v1/integrations/promotion: Replace configuration
  • DELETE v1/integrations/promotion: Remove integration
  • PATCH v1/integrations/promotion: Update settings
If you have suggestions for improving this article, let us know!