1. Integration and Import/Export Guide
  2. Oracle Internal Imports and Exports
  3. Oracle Retail Promotion Engine Integration

Oracle Retail Promotion Engine Integration

Order Administration is integrated to the Oracle Retail Promotion Engine Cloud Service (ORPE) following the v23.2.401.0 update. When configured, Order Administration will bypass some of the inherent promotional pricing options during order entry, making a REST call to provide the order (cart) details for evaluation by ORPE. The promotion engine performs a comprehensive evaluation of the cart, identifies the applicable offers, and responds with the discounted price applied for qualifying merchandise lines. If shipping rewards are included in the response, Order Administration performs additional validation and calculations before they are applied to the order.

Retailers define deals and promotions using Customer Engagement and then automatically propagate the promotion data to ORPE. This allows the retailers to submit orders (carts) from various external systems (ecommerce, point of sale, order management, and so on) to be centrally evaluated against a single source of promotion data.

The following features in Order Administration will communicate with ORPE for applying promotions:

  • Modern View Order Entry

  • Classic View Order Entry when editing / accepting a batch of orders in error

  • CWOrderIn version 12.0 when it indicates discounts are not already applied

  • Customer Membership Child Order Generation (EGMO)

The following features will not communicate with ORPE: Order Maintenance, OB Fulfillment Order Creation, and ChannelAdvisor.

Note:

Order Administration Modern View Order Summary does NOT communicate with ORPE when an existing order is maintained. If a new line is added in maintenance, it will be priced based on the Order Administration price method hierarchy. If an existing line quantity is changed in maintenance, the price will remain unchanged. The line will not be re-evaluated by Order Administration, and it will not be sent to ORPE for evaluation.

Order Administration Classic View does not allow the reprice function with ORPE enabled, nor does it call ORPE during interactive order entry or order maintenance. However the Edit/Accept batch process triggered from Classic View does call ORPE to evaluate orders which have corrected within the Error Batch.

All promotion details successfully applied by ORPE are stored for display within the Modern View user interface (UI) and incorporated into various outbound API’s and integration files including:

  • Modern View Order Summary and Invoice tabs

  • CWInvoiceOut version 7.0

  • CWOrderOut version 12.0

  • CWEmailOut version13.0

  • ReSA RTLog Output File

  • ORCE POSLog Output File

ORPE Setup Requirements

Required Properties: The following properties are available to configure the integration with ORPE:

  • oms.promotion.engine.service.url (PROP): The full URL for the promotion engine service. Provided by your Oracle representative. Defaults to blank.

  • oms.promotion.engine.service.timeout (CPRP): The number of seconds to wait before deal requests from Order Administration to the ORPE Promotion time out. Defaults to 500 seconds.

  • oms.promotion.engine.service.token.url (CPRP): The URL to use when requesting a token for Oauth authentication. Provided by your Oracle representative. Defaults to blank.

  • orce.coupon.service.url.suffix (PROP): The suffix to append to the ORCE_CUSTOMER_SERVICE_PREFIX for Serialized ORCE Coupon Service for validation and redemption of a serialized coupon.

Note:

When calling the ORCE Coupon Service, Order Administration builds the URL using the ORCE_CUSTOMER_SERVICE_PREFIX, SCV L50 and the orce.coupon.service.url.suffix value.

Authentication configuration: To configure the promotion engine integration, use ORPE Promotion and ORCE Coupon Service at the Work with Outbound Web Service Authentication screen (WWSA). Only OAuth authentication is supported. Client ID and Client Secret will be delivered blank by default for each company.

Required system control value settings: Use the following system control values to enable use of ORPE:

  • Use ORPE Promotion Engine (M77): Select this system control value to enable use of ORPE for a specific company. Required for ORPE Integration.

  • Price Override Reason for ORPE Discounts (M78): Select the price override reason code to apply to order lines that are discounted through use of the Promotion Engine. Required for ORPE Integration.

  • Use ORCE Serialized Coupons (M79): Select this system control value to use Serialized Coupons with ORPE.

  • ORCE Serialized Coupon Prefix Length (M80): This system control value stores the Serialized coupon codes prefix length value. It must match the value defined in Property Configuration Promotion Coupon Length within ORCE.

Also, the following existing system control values are used:

  • Allow Manual Entry of Promotion Code (I63): Must be selected to see the new Coupons section within in the Order Summary panel.

  • ORCE Integration Item ID (L38): Required for ORPE Integration.

  • ORCE Organization Descriptor (L50): Required for Serialized Coupons with ORPE.

  • Display Order Line Discount Messages (F01): Impacts display of ORPE promotion details.

  • Display Discount On Order Recap Screen (D38): Impacts display of ORPE promotion details.

  • Default Location for ORCE Integration (K69): Required for integration with ORCE and ORPE.

Order API Enhancements

The Order API (CWOrderIn) now allows the ability to indicate the order should be sent to ORPE for promotions to be applied. Additionally, it includes new attributes to allow an external merchant application to pass discount details already applied by ORPE externally. The changes include:

  • The already_eval_by_promote attribute was renamed to already_eval_by_promo_engine.

  • A new repeating element (Shipping_Rewards) was added within the ship to element, allowing retailers to include shipping award details that were already applied by an external system.

    A new repeating element (Discount_Rewards) was added within the item element, allowing retailers to include order line discount details that were already applied by an external system.

Note:

The Order API does not currently support ORCE coupon codes or targeted customer promotions when passed in from an external merchant application. See the Web Services Guide on My Oracle Support (ID 2953017.1) for more information.

For more information on Order API documentation and for a comprehensive list of available attributes, sample XML messages, DTD’s and XSD’s, see the Web Services Guide on My Oracle Support (ID 2953017.1).

Deal Types and Promotions

The Order Administration integration now supports the ORPE deal types included below. These deal types are configured in Customer Engagement.

  • BOGO: Buy X Get X and Buy X Get Y

  • LINE ITEM: Line Item Discount

  • GROUP PRICE: Kit

  • SUBTOTAL: Transaction Discount

For each supported deal type, Order Administration will allow shipping awards to optionally apply an Override Shipping Method (Ship Via) and/or the ability to define a discount from the following options:

  • an Override Price (flat shipping fee),

  • an Amount Off (Order Administration deducts the value from the shipping calculation) or

  • a Percent Off (Order Administration calculates the discount percentage amount then deducts the value from the shipping calculation)

Note:

All Shipping Award discount options are applied within Order Administration as a shipping override.

The Order Administration integration currently supports product and coupon promotion types (both single-use and multi-use coupons) and incorporates cart data for evaluation of location qualifiers and promotion audience rules (exclusive and non-exclusive).

Note:

Coupon Codes are not supported through the Order API. They are only supported when entered through Modern View Order Entry.

Coupons the integration with ORPE supports two options for coupon promotions, (Serialized and Non-Serialized).

  • A Serialized Coupon allows the retailer to generate coupons, each with a unique serial number, generally for a one-time use. Depending on user authority, a contact center agent may have the ability to allow a previously redeemed serialized coupon to be submitted to ORPE. In this situation, ORPE will apply the coupon discount as long as the cart meets the coupon requirements.

    • If the Contact Center user has authority to the Allow Redeemed ORCE Serialized Coupon to be Overridden secured feature, they can submit a previously redeemed serialized coupon to ORPE by clicking a new attempt Reuse button. For example: If the coupon represented a 10% discount on handbags, it would be automatically applied as long as the cart included a handbag.

  • A Non-Serialized Coupon allows a retailer to define a coupon code for the promotion which can be used multiple times. For example, the coupon code ‘SHOE20’ may represent a coupon code that a customer can use multiple times to receive a 20% discount on a shoe purchase.

For Failed redeems due to a communication failure with ORCE or another issue, the retailer can generate a report through Customer Reports or RDS based on the Order Transaction History record where the serialized coupon was not redeemed.

About location qualifiers: When submitting the cart information to ORPE, Order Administration includes location identifier (value from SCV K69 – Default Location for ORCE Integration), so that ORPE can evaluate and either qualify or exclude the cart based on location rules defined for the promotion in ORCE.

About audience rules: Audience rules can be defined within each promotion created from the ORCE UI. By default, the audience defaults to All which means that the promotion is available to anyone. (Everyone who buys the items included in the promotion, gets the offer discount.) However, the retailer can optionally define the promotion audience as Exclusive or Non-Exclusive and include additional selections options.

Note:

To identify customers that are included in exclusive promotions, Order Administration first makes a call to ORCE using the retrieveCustomer method. Any Exclusive Promotion details included in the response are then submitted with the cart for ORPE evaluation. If the cart qualifies for the exclusive promotion, the respective discounts are applied to the order.

Targeted Customer Promotions: the integration with ORPE supports applying customer targeted promotions tied to a customer in ORCE. These promotions are set up as Audience Rules within the promotion in ORCE.

  • Exclusive Audience: When the retailer defines the promotion audience as Exclusive, this means that only the customers identified in the target group (segment) are eligible to receive the promotion.

  • Non-Exclusive Audience: When the retailer defines the promotion audience as Non-Exclusive, this means that all customers are eligible to receive the promotion.

During Modern View Order Entry, if the customer exists in ORCE and qualifies for an Exclusive Promotion, that will automatically be passed into ORPE as additional qualifiers in the cart and the respective discounts are applied to the order.

Entitlement Coupons

Order Administration supports Entitlement coupons to be included from an external system when submitting the order using the Order API as well as providing the ability to retrieve and apply available entitlement coupons based on a customer's loyalty cards during Modern View Order Entry. 

Entitlements are a type of coupon code that triggers an offer/deal that is tied to a loyalty program. Entitlements are not set up the same as coupons. First the customer must be set up/enrolled in a loyalty program in Customer Engagement (ORCE), then based on points earned an entitlement coupon is issued, specific to that customer. 

Entitlements are supported when:

  • ORCE Customer Integration (L37) system control value is set to INTERACT

  • Use ORCE Loyalty (M06) system control value is set to Yes

  • Use ORPE Promotion Engine (M77) system control value is set to Yes

  • The Source Code assigned to the Order has the Price Method set to Regular Plus Reprice

  • There is at least one Entitlement coupon for the selected Loyalty Card

Within Order Entry, the number of available entitlement coupons is displayed on the Select Card window. Once a loyalty card is assigned, entitlement coupons will be retrieved from Customer Engagement (ORCE) for that specific card only. You cannot apply entitlements associated to other loyalty cards not assigned to the order.

In the Order Summary panel, if entitlement coupons are available, an Entitlement Coupons available link or edit icon will be displayed within the Customer section. Advance into the Entitlement Coupons window to select/deselect which coupons should be submitted for evaluation during the order review step.

At final order submit, each Entitlement coupon that is successfully applied by ORPE is:

  • Redeemed in ORCE. An Order Activity record is written for each successful or failed redemption request.

  • Stored in discount history coupon tables.

  • Displayed in a tooltip for a specific order line in MV Order Summary and Invoice tabs. Additionally, is included in the merchandise and shipping discount totals within the Order Totals section of the Order Summary tab. Only displayed if Display Order Line Discount Message (F01) system control value is set to Y.

  • Displayed in the Promotion Details drawer in MV Order Summary. Only displayed if Display Discount on Order Recap Screen (D38) system control value is set to Y.

Entitlement coupons that apply merchandise and shipping discounts are included in:

  • Customer Engagement POSLog within the RetailPriceModifier object.

  • ReSA RTLog within the IDISC record. The Coupon Reference Number value is populated with a coupon_type of ‘entitlementCoupon’.

Order Entry Changes in Modern View

Modern View Order Entry has been changed when SCV Use ORPE Promotion Engine (M77) is enabled to support the deal types and promotions. The following now occurs:

  • The Promotion Code and the Discount Percent fields are hidden from view.

    Addition Order Details showing hidden fields

  • When Allow Manual Entry of Promotion Code (I63) system control value is enabled there is a new Coupons section in the Order Summary panel.

    New Coupon section in Order Summary panel

  • When using a source code with price method Reg Plus Reprice and the Add Coupon Code button is selected from the Coupons section of the Order Summary panel, a modal window opens so that the user can enter coupon codes. Entered coupons are evaluated during order review, rather than immediately upon closing the modal window, since additional order changes may be incorporated.

    coupon code entry

    • If the source code used at order entry has price method other than Reg Plus Reprice, a warning message is displayed within the Coupons section advising Source code does not support Coupons and the Add Coupon Code button is not displayed.

  • At the Review step, or after Refresh Order if changes were added, the Coupons section may display a message indicating that Codes were not applied; this occurs if any serialized coupons were previously redeemed or coupons were submitted for evaluation but were not applied.

  • At the Final Submit step, a System Update entry is written in the Order Activity tab when:

    • a coupon code is entered but not successfully applied by ORPE.

    • a serialized coupon is successfully applied by ORPE and it is successfully redeemed or not.

If the Contact Center user has authority to the Allow Redeemed ORCE Serialized Coupon to be Overridden secured feature, they can submit a previously redeemed serialized coupon to ORPE by clicking a new Attempt Reuse link. For example: If the coupon represented a 10% discount on handbags, it would be automatically applied as long as the cart included a handbag.

Discount Display in Modern View Order Entry and Summary

Item Level Discounts

When the offer price is greater than the unit price, the system now displays the offer price with a strike through before the discounted Unit Price. This is controlled by Display Order Line Discount Messages (F01) system control value.

Additionally, hovering over a new icon will display the discount details for each promotion applied, including the unit discount amount and the associated deal description. If the promotion was triggered by a coupon, the coupon code is included in parenthesis following the deal description.

F01 enabled showing offer price with strikethrough

Order Level Discounts

The Order Total section now displays an icon in front of each of the labels that include an ORPE discount (Merchandise and/or Shipping). This is controlled by Display Discount On Order Recap Screen (D38) system control value.

Additionally, an informational message will display below the totals for each ORPE discount type (Merchandise and/or Shipping) showing the total promotion discounts for the order.

Note:

The calculated Merchandise Discounts and Shipping Discounts are limited to discounts applied by ORPE. If additional discounts were applied based on price methods, manual price overrides, and so on, those discounts would not be reflected in the Merchandise Discounts or Shipping Discounts.

When no ORPE promotion discounts have been applied to the order, but there is a delta between the offer price and the actual selling price (due to price method discount, price overrides, and so on) an Order Discount informational message will display below the totals. The Order Discount value is a calculation of the sum of the extended offer prices for all lines, minus the total extended selling price for all lines.

Promotion Details

For orders including promotional discounts applied by ORPE (or submitted through the Order API with the already_eval_by_promo_engine attribute set to Y and containing reward data) a Promotion Details button will display within the Ship To section of Modern View Order Summary. Summary level promotion details per ship-to will be displayed in this panel.

From the Invoices tab, once an invoice has been selected the same item level and order level promotion discount data is available, however the lines displayed will be limited to those included on that specific invoice.

When there is a communication failure (error response, timeout) preventing Order Administration from successfully receiving the applyDeals response (via Modern View Order Entry, Error Batch Edit/Accept Processing or the Order API),details are written to the ORPE log.  

If the error results from an order that was submitted from MV Order Entry, prior to the 'final submit', communication message advising that a communication error occurred is displayed. 

If the error results from an order that was submitted from MV Order Entry, during the 'final submit', a snackbar message advising that a communication error occurred is displayed. 

 

Discount History

When ORPE is enabled, additional order line discounts are captured and stored in the discount history tables. This includes automatic pricing/discounting as well as manual discounting performed in Modern View Order Entry and Maintenance, Classic View Order Entry and Maintenance, discounts relating to loyalty awards applied and discounts assessed on orders submitted via the CWOrderIn API. Individual discount details are displayed within Modern View Order Summary and passed in CWInvoiceOut and CWOrderOut.

The ReSA RTLog and the ORCE POSLog includes individual discount details for promotions and writes a delta record to make up the difference between the offer price and the discounted price, after the promotion discounts have been incorporated.