Headless (OCAPI) Architecture

1. Configuring OCAPI

This section describes how to configure Shop API resources under OCAPI settings. ESW recommends that you configure Shop API version 23.1 or later for optimum utilization of the cartridge.

You can generate a new client ID and password by logging in to the Commerce Cloud Account Manager.

Adding Shop API Resources

For the cartridge to work, you must add Shop API resources to the cartridge.

To add resources:

1. On the target site, go to Administration > Site Development > Open Commerce API Settings.
2. From the Select type drop-down, select Shop.
3. From the Select Context drop-down, select the appropriate context, for example, Global (organization-wide) or site-specific.
4. Enter the OCAPI Shop API resources provided in the ocapi-configurations.json file in the documentation folder.
5. Update the client_id with the one you generated from the Commerce Cloud Account Manager.
6. Click Save.

int_eshopworld_headless is an overlay cartridge that includes all OCAPI customizations. You can duplicate the customizations in your cartridge by including the function calls in your OCAPI hook call files.

3. OCAPI Endpoint Customizations

3.1 Product Detail Page (PDP)

Request

GET http://hostname:port/dw/shop/v{OCAPI_VERSION}/products/{id}?expand=prices

Request Parameters

OCAPI Response

Product Document (out-of-the-box pricing attributes are converted and assigned to ESW custom attributes.)

Pricing Attributes Mapping (PDP)

3.2 Product Listing Page (PLP/CLP)

You can also add search-related query parameters to the URL as well.

Request

GET http://hostname:port/dw/shop/v{OCAPI_VERSION}/product_search?expand=prices

Request Parameters

OCAPI Response

Product Search Result Hits (out-of-the-box pricing attributes are converted and assigned to ESW custom attributes.)

Pricing Attributes Mapping (PLP/CLP)

Extension Points (PDP + PLP/CLP)

3.3 Cart or Basket Page

Basket / Cart Customizations (High level)

ESW uses extension scripts to:

• Apply override price book logic (Fixed Pricing / Override Price Books)
• Recalculate basket totals and apply ESW conversions for dynamic pricing countries

Basket Pricing / Flags (Custom attributes referenced)

Extension Points (Basket)

For more information on how OCAPI response attributes can be used to display or represent the different prices on the Cart Page, see Headless (OCAPI) Attributes Mapping with Cart.

4. ESW Checkout Redirect (OCAPI Order + ESW Checkout)

4.1 Create Order (Shop API)

Request

POST http://hostname:port/dw/shop/v{OCAPI_VERSION}/orders

Request Parameters

OCAPI Response

orderResponse Document (appended with ESW PreOrder Service Response)

ESW PreOrder Service Response — SUCCESS (example)

"c_eswPreOrderResponseStatus": "OK",
"c_eswPreOrderResponse": {
  "preOrderCode": "7d06f6ec-fbd4-417b-8275-67b3e0d94de1",
  "orderNumber": "7d06f6ec-fbd4-417b-8275-67b3e0d94de1",
  "redirectUrl": "https://checkout-ui-plugus.sandbox.eshopworld.com/7d06f6..."
}

ESW PreOrder Service Response — FAILED (example)

"c_eswPreOrderResponseStatus": "ERROR",
"c_eswPreOrderResponse": [
  {
    "message": "RetailerCartId is required.",
    "code": 8
  }
]

4.2 Order Hook Extension Points

5. Basket Creation Request Payload (Minimum Example)

The following code sample shows the minimum request payload required to create an ESW Checkout Order:

For information on Checkout API and its request body attributes, see the Checkout API.
For information on the OCAPI endpoints, see SFCC - Shop API Resources.

{
  "product_items": [
    {
      "product_id": "750518699721",
      "quantity": 1
    },
    {
      "product_id": "750518699769",
      "quantity": 1
    }
  ],
  "shipments": [
    {
      "shipping_method": {
        "id": "POST"
      }
    }
  ],
  "currency": "USD"
}

6. Order Confirmation

The ESW Order Confirmation is a webhook call initiated from the ESW system to the retailer system. Similar to other architectures, the Headless (OCAPI) Architecture also has a similar flow for Order Confirmation.

For order confirmation requests in Headless OCAPI:

• EswHL-Notify endpoint is used for SiteGenesis compatible architecture
• EswRefArchHL-Notify endpoint is used for SFRA compatible architecture
  Configurations for this can be done using the ESW Metadata Items custom site preference under ESW Checkout Configuration.

7. Generic Price Conversion Endpoint

SFCC Custom Web Endpoint

• SiteGenesis compatible Architecture:
  • GET https://hostname/on/demandware.store/Sites-SiteGenesis-Site/en_US/EswHL-Price
• SFRA compatible Architecture:
  • GET https://hostname/on/demandware.store/Sites-RefArch-Site/en_US/EswRefArchHL-Price

Request Parameters

Response

The formatted converted price in the shopper currency.

8. Order Cancelation

The ESW Order Cancelation is a webhook call that is initiated from the ESW system to the retailer’s system.

SFCC Custom Web Endpoint (Headless OCAPI)

For order cancelation requests in Headless OCAPI:

• EswHL-CancelOrder endpoint is used for SiteGenesis compatible architecture.
• EswRefArchHL-CancelOrder endpoint is used for SFRA compatible architecture.

This can be configured by importing systemobjects_headless.xml file from sitesdata/meta directory path.