---
title: Custom promotion discounts
slug: custom-promotion-discounts
abstract: This guide explains how to use promotion integration with integration events to handle scenarios beyond the Rules Engine capabilities.
content_type: how-to
audience: \[developer, architect]
---
# Custom promotion 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.

![ ](https://doc.sitecore.com/api/markdown-image/ordercloud/en/developers/platform/images/8394f0625ee44398b592c9f5f127bbe5.png)

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

## Related reading

- [Promotion enhancements](https://doc.sitecore.com/ordercloud/en/developers/platform/promotions.html#promotion-enhancements)
- [How to calculate tax with OrderCloud](https://doc.sitecore.com/ordercloud/en/developers/platform/order-checkout.html#how-to-calculate-tax-with-ordercloud)
- [Order returns - handling calculations](https://doc.sitecore.com/ordercloud/en/developers/platform/order-returns.html#order-returns---handling-calculations)