1. Extending Oracle Commerce
  2. Assign Catalogs and Price Groups to Shoppers
  3. Configure the External Price Group and Catalog webhook

Configure the External Price Group and Catalog webhook

The External Price Group and Catalog webhook sends information to an external system which determines which catalog and price groups to display to a shopper and sends that information in a response.

If Commerce cannot connect to the external system (for example in the event of an outage), or if the webhook response contains incorrect information, Commerce uses the catalog and price groups assigned to the current site or account.

The custom widget you create invokes the webhook to send shopper-context information to the external system, which responds with the catalog and price groups to display. Then, when the shopper places the order (or when a scheduled order is triggered, or an approver opens an order for approval), the server invokes the webhook, which sends the context data to the external system to verify that the catalog and price group used to place the order are still valid. This step is used to ensure that items in the cart are still available and that the prices in the cart have not been modified.

If the webhook response returns a different catalog and price group than the ones that were assigned when the shopper created the order, or if the default catalog and price group are used because the webhook fails, the server verifies that all items in the order are still available at the same price. If they are, the order progresses to the next step.

If all the items in the order are not available at the same prices, an error message is displayed and the shopper can change items in the cart before submitting the order again. For scheduled orders, the order fails. For an order that has been opened by an approver, an error message is displayed and the order is returned to the Pending Approval list.

Note: If your store supports scheduled orders and order approvals, make sure you are using the latest versions of the layouts and widgets described in Create Scheduled Orders and Enable Order Approvals.

The following properties are sent in the JSON request body of the of the External Price Group and Catalog webhook:

  • Profile details for the shopper. The webhook sends all the properties (including custom properties) that are sent with the Shopper Account Update webhook.

Note: The webhook does not send any information about the shopper’s audience membership.

  • If the store is configured for account-based commerce, details about the current account. The webhook sends all the properties (including custom properties) that are sent with the Account Update webhook.
  • If the webhook is triggered because an order is placed, a scheduled order is instantiated, or an order is approved, the webhook body also includes details about the order. See Order Submit request example for a sample JSON representation of an order in a webhook body.

The webhook body does not include certain payment details, such as credit card information. See Understand webhooks and PCI DSS compliance for information about payment details that are excluded from the request.

  • If any custom order properties have their externalShopperContext attribute set to true, the webhook body also includes those order properties as a map of name/value pairs. See Create the custom order properties for more information.

For example, the following portion of a sample request body sends the values for the custom properties eventProp1Key and eventProp2Key.

"contextData":{
   "userContext":"{\"eventProp1Key\":\"eventasas1\",\"eventProp2Key\":\"true\"}"
   }

To send this data to the external system, you configure the webhook by specifying the URL, username, and password for accessing the system. (See Configure webhooks for details.) You must also configure the external system to read the request data, determine which catalog and price groups Commerce should display, and send a response. The following table describes the properties that should be returned in the JSON response body of the External Price Group and Catalog webhook.

Property Description
responseCode

An integer that specifies which catalog and price groups to use.

When the webhook is triggered during a context change, 0 specifies that Commerce displays the catalog and price groups assigned to the current site or, for account-based commerce, to the current account. If the value is 1, Commerce displays the catalog and price groups whose IDs are returned in the body of the response.

When an order is validated, 0 specifies that the catalog and price groups assigned to the current site or account are valid for the order. If the value is 1, the catalog and price groups assigned to the shopper are valid for the order. If the value is 2, the items or prices in the order are not valid. If the response code is 0 or 1, the order is submitted or opened for approval. If the response code is 2, the order is not submitted, and an error is displayed.
Message A string that describes the responseCode.
defaultPriceListGroup A string that is the ID of the price group whose prices are displayed by default.
defaultAdditionalPriceListGroups An array of strings that are the IDs of additional price groups. Additional price groups let a shopper select from a list of currencies your store supports and see those prices on your store.
defaultCatalog A string that is the ID of the catalog to use.

For example, if the external system determines that a shopper should see the North American Parts (NAParts) catalog priced with the defaultPriceGroup with two additional price groups (plgCAD and plgMXN), the response body might be: 

{
  "defaultAdditionalPriceListGroups": [
    "plgInr",
    "plgEuro"
  ],
  "defaultPriceListGroup": "defaultPriceGroup",
  "defaultCatalog": "NAParts",
  "message": "use this data",
  "responseCode": 1
}