Promotion enhancements

OrderCloud Promotions have been enhanced with new properties and endpoints to provide greater flexibility in promotion management and application.

New properties

AutoApply property

Default value: false

This property enables:

• Automatic promotion application
• Priority-based application order
• Controlled promotion sequencing

Active property

Default value: true

This property controls:

• Promotion evaluation status
• Buyer user access
• Historical record keeping

Behavior:

• Inactive promotions (Active = false):
  • Not evaluated for .../applypromotions
  • Not evaluated for .../eligiblepromotions
  • Not returned from v1/me/promotions
  • Removed from unsubmitted orders upon deactivation
  • Remain accessible via administrative endpoints
  • Available for future reactivation

Priority property

Value type: Nullable

This property enables:

• Controlled promotion application order
• Flexible priority values
• Sequential promotion processing

Implementation notes:

• No strict sequencing rules
• Used by applypromotions and refreshpromotions
• Determines evaluation order

New endpoints

Eligible promotions endpoints

v1/orders/{direction}/{orderID}/eligiblepromotions and v1/cart/eligiblepromotions

These endpoints support:

• Listing eligible promotions for orders
• Displaying promo codes during checkout
• Enhanced promotion-based UI features

Refresh promotions endpoints

v1/orders/{direction}/{orderID}/refreshpromotions and v1/cart/refreshpromotions

These endpoints handle:

Automatic promotion application

• Applies eligible AutoApply promotions
• Sorts by Priority value
• Processes null Priority values last
• Limits to 100 promotions per API call

Promotion removal

• Removes ineligible applied promotions
• Handles CanCombine conflicts
• Processes Priority-based removals

Promotion recalculation

• Recalculates existing promotion discounts
• Updates order totals
• Maintains promotion integrity

Response details

Returns arrays of:

• PromosAdded: Newly applied promotions
• PromosRemoved: Removed promotions

Note: Prefer /refreshpromotions over /applypromotions for most use cases.

Apply promotions endpoints

v1/orders/{direction}/{orderID}/applypromotions and v1/cart/applypromotions

These endpoints provide:

Automatic application

• Processes eligible AutoApply promotions
• Sorts by Priority value
• Handles null Priority values last
• Limits to 100 promotions per call

Response format

Returns the complete Order object with:

• Applied promotions
• Updated totals
• Order details

Related reading

• Product collection enhancements
• Rules-based promotion expressions
• Bundle products for enhanced commerce experiences