Use promotions from an external system
When working with promotions, you may want to use either Oracle Commerce and/or an external system for issuing your promotions.
When a pricing operation is initiated, the regular item and order pricing occurs. After order pricing, the system invokes the External Promotions webhook. This webhook allows an external system that you have configured, as outlined earlier in this chapter, to discount order and item prices determined by Commerce. Commerce receives a request to update pricing to items within the cart and the pricing changes are applied and displayed to the shopper.
The following properties are used for external promotion requests:
| Property | Description |
|---|---|
externalCoupons |
Contains the external coupons list. |
order |
Contains the order object, which contains the order ID. |
profile |
Contains the profile repository item that is added to the request as a top-level JSON object. |
serviceName |
Contains the name of the webhook service. |
ExternalPromotionsIds |
Contains the list of external promotion IDs provided during the return process. |
The following is an example of a request:
{
"secondaryCurrencyCode": "string",
"exchangeRate": 0,
"profile": {},
"currencyCode": "string",
"operation": "string",
"order": {
"priceInfo": {},
"discountInfo": {
"orderCouponsMap": [
{
"promotionLevel": "string",
"totalAdjustment": "string",
"promotionDesc": "string",
"promotionId": "string"
}
],
"orderDiscount": 0,
"shippingDiscount": 0
},
"shoppingCart": {
"numberOfItems": 2,
"items": [
{
"unitPrice": 24.99,
"amount": 36.98,
"quantity": 2,
"detailedItemPriceInfo": [
{
"discounted": false,
"secondaryCurrencyTaxAmount": 0,
"amount": 24.99,
"quantity": 1,
"tax": 0,
"orderDiscountShare": 0,
"detailedUnitPrice": 24.99,
"currencyCode": "USD",
"detailedItemPriceInfoID": "String"
},
{
"discounted": true,
"secondaryCurrencyTaxAmount": 0,
"amount": 11.99,
"quantity": 1,
"tax": 0,
"orderDiscountShare": 0,
"detailedUnitPrice": 11.99,
"currencyCode": "USD",
"detailedItemPriceInfoID": "String"
}
],
"catRefId": "string",
"externalRecurringChargeDuration": "string",
"discountInfo": [
{
"promotionLongDesc": "<p>Save $13 on Wonderland OR
XBOX 360</p>",
"promotionName": "Explicit Item Discount -
SAVE13DOLLARS",
"promotionLevel": "item",
"coupon": "SAVE13DOLLARS",
"totalAdjustment": "-13.0",
"promotionDesc": "Explicit Item Discount -
SAVE13DOLLARS",
"promotionId": "explicitItemAmountDiscount",
"giftWithPurchaseDiscountInfo": []
}
]
}
]
},
"coupons": [
{
"code": "",
"description": "",
"status": "",
"level": "",
"id": ""
}
],
"shippingAddress": {},
"siteId": "string"
},
"externalCoupons": [
{
"code": "EXTERNALCOUPON",
"description": "",
"status": "",
"level": "",
"id": ""
}
]
}
The orderCouponsMap includes the promotionID, which provides the external system with the ability to differentiate between internal promotions that have been applied to the order and those promotions that have been applied by the external system.
The External Promotions webhook responds with either an error code or a status message. Note that the external system must provide a unique ID for each promotion to be applied. This ID should be unique between both external promotions and internal promotions. External promotion IDs must not clash with internal IDs. If an external promotion uses an ID that matches the ID of an internal item or order promotion that has already been applied to the order, the external promotion is ignored.
The following properties are used for external promotion response:
| Property | Type | Description |
|---|---|---|
adjustmentAmount |
Number | The amount to adjust the target item or order by. |
adjustmentOperation |
String |
The external promotion adjustment operation to apply. Values for this property include:
|
adjustmentOrdering |
String | The order of items to target for adjustment based on the
highestFirst or lowestFirst
priced.
|
coupon |
String | The coupon ID. |
description |
String | A description of the external promotion being applied by the adjustment. |
displayName |
String | The promotion display name. |
id |
String | The ID of the commerce item in the cart to be adjusted. |
promotionId |
String | The external promotion ID. |
quantity |
Number | The quantity of items to be adjusted. |
The following is an example of the body of a response:
{
"responseCode":"6101",
"promotionAdjustments": [
{
"adjustmentOperation": "adjustItemPrice",
"promotionId": "EP1001",
"description": "$20 discount on XBOX 360",
"id": "ci6000413",
"quantity": "2",
"adjustmentOrdering": "highestFirst",
"adjustmentAmount": "-20",
"displayName": "XBOX Forever",
"coupon": "20DOLLARDISCOUNTXBOX"
},
{
"adjustmentOperation": "adjustOrderPrice",
"promotionId": "EP1003",
"description": "$50 off order when total above $300",
"adjustmentAmount": "-50",
"displayName": "50DollarDiscount"
}
]
}
Once the webhook responds, the operation described in the response, or any errors, are reported back.
Cancel external promotion orders
If an order is cancelled during the remorse period, the Cancellation webhook is triggered. This could allow details of the cancelled orders to be posted to the external pricing system upon cancellation, releasing any promotions that were applied during the order so that they may be reapplied if necessary. The Cancellation webhook contains all of the order-related information, as well as the reason for the cancellation.
If a remorse period is in effect, the Submit Order webhook is not fired until the end of the remorse period. Use the Remorse Period Started webhook to give details of the order to an external system prior to order being submit. For example, you could use the Remorse Period Started webhook to mark promotions to ensure that they are not unknowingly reapplied if a shopper creates another order during the remorse period.
For further information on remorse periods, refer to Understand the remorse period.