> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/shopify/salesforce-commerce-cloud/cartridge-setup/headless-ocapi-architecture.md). # Headless (OCAPI) Architecture ### 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. ### OCAPI Endpoint Customizations #### Product Detail Page (PDP) **Request** `GET http://hostname:port/dw/shop/v{OCAPI_VERSION}/products/{id}?expand=prices` **Request Parameters** | ESW Parameters | Description | Notes | | -------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `country-code` (Required) | Two-letter ISO code of the shopper's country. | - | | `currency-code` (Optional) | Three-letter ISO code of the shopper's local currency. | If the currency code is provided in the request, the ESW plugin uses this currency. If not provided, the ESW plugin uses the currency code provided in the **ESW Default Country Currency Mapping** site preference. | | `currency` (Optional) | Three-letter ISO code of the shopper's local currency. | This is a standard OCAPI parameter. The parameter is required for **Fixed Pricing** and **Override Price Books**. | **OCAPI Response** Product Document (out-of-the-box pricing attributes are converted and assigned to ESW custom attributes.) **Pricing Attributes Mapping (PDP)** | ESW Attribute | Type | Product Base Pricing Attribute | | ------------------------- | -------------------- | ------------------------------ | | `c_eswPrice` | Decimal | `price` | | `c_eswPrice_max` | Decimal | `price_max` | | `c_eswPrice_per_unit` | Decimal | `price_per_unit` | | `c_eswPrice_per_unit_max` | Decimal | `price_per_unit_max` | | `c_eswPrices` | Map\[String, Number] | `prices` | | `c_shopperCurrency` | String (3-char ISO) | - | #### 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** | Parameter | Type | Description | | ------------------------ | ------- | ------------------------------------------------------------------------ | | `c_eswReturnProhibited` | Boolean | `true/false` if product return is prohibited in current shopper country. | | `c_eswRestrictedProduct` | Boolean | `true/false` if product is restricted in current shopper country. | **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)** | ESW Attribute | Data Type | Product Base Pricing Attribute | | ------------------------- | -------------------- | ------------------------------------------------------------------------ | | `c_eswPrice` | Decimal | `price` | | `c_eswPrice_max` | Decimal | `price_max` | | `c_eswPrice_per_unit` | Decimal | `price_per_unit` | | `c_eswPrice_per_unit_max` | Decimal | `price_per_unit_max` | | `c_eswPrices` | Map\[String, Number] | `prices` | | `c_shopperCurrency` | String (3-char ISO) | - | | `c_eswReturnProhibited` | Boolean | `true/false` if product return is prohibited in current shopper country. | | `c_eswRestrictedProduct` | Boolean | `true/false` if product is restricted in current shopper country. | **Extension Points (PDP + PLP/CLP)** | Extension Point | ESW Extension Script | Notes | | ------------------------------------------------ | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `dw.ocapi.shop.product.beforeGET` | `/int_eshopworld_headless/cartridge/scripts/ocapi/shop/hooks/setOverridePriceBook.js` | Mainly used for **Fixed Pricing** and **Override Price Book** to get prices directly from the price book. | | `dw.ocapi.shop.product.modifyGETResponse` | `/int_eshopworld_headless/cartridge/scripts/ocapi/shop/hooks/pdpPriceHook.js` | Used for **dynamic/calculated** prices. Skips dynamic calculations for **Fixed Pricing model** countries. | | `dw.ocapi.shop.product_search.modifyGETResponse` | `/int_eshopworld_headless/cartridge/scripts/ocapi/shop/hooks/plpPriceHook.js` | Used for **dynamic/calculated** prices. Skips dynamic calculations for **Fixed Pricing model** countries. | #### 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)** | Attribute | Type | Description | | ------------------------ | ------- | ----------------------------------------------------------------- | | `c_eswUnitPrice` | Decimal | `basePrice` (per unit) | | `c_eswReturnProhibited` | Boolean | `true/false` if return is prohibited in current shopper country. | | `c_eswRestrictedProduct` | Boolean | `true/false` if product is restricted in current shopper country. | **Extension Points (Basket)** | Extension Point | ESW Extension Script | Notes | | -------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `dw.ocapi.shop.basket.afterPOST` | `/int_eshopworld_headless/cartridge/scripts/ocapi/shop/hooks/setOverridePriceBook.js` | Mainly used for **Fixed Pricing** and **Override Price Book** to get prices directly from the price book. | | `dw.order.calculate` | `/int_eshopworld_headless/cartridge/scripts/cart/calculate.js` | Standard SFCC `calculate.js` extension script calculates/recalculates the basket sent in the request. The customized/added function call `eswBasketPriceConversions` is used for dynamic/calculated prices and skips dynamic calculations for Fixed Pricing model countries. | > 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**. ### ESW Checkout Redirect (OCAPI Order + ESW Checkout) #### Create Order (Shop API) **Request** `POST http://hostname:port/dw/shop/v{OCAPI_VERSION}/orders` **Request Parameters** | ESW Parameters | Description | Notes | | -------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `country-code` (Required) | Two-letter ISO code of the shopper's country. | - | | `currency-code` (Optional) | Three-letter ISO code of the shopper's local currency. | If the currency code is provided in the request, the ESW plugin uses this currency. If not provided, the ESW plugin uses the currency code provided in the **ESW Default Country Currency Mapping** site preference. | **OCAPI Response** `orderResponse` Document (appended with ESW PreOrder Service Response) **ESW PreOrder Service Response — SUCCESS (example)** ```json "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)** ```json "c_eswPreOrderResponseStatus": "ERROR", "c_eswPreOrderResponse": [ { "message": "RetailerCartId is required.", "code": 8 } ] ``` #### Order Hook Extension Points | Extension Point | ESW Extension Script | Notes | | ---------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `dw.ocapi.shop.order.beforePOST` | `/int_eshopworld_headless/cartridge/scripts/ocapi/shop/hooks/orderHooks.js` | Used for Fixed Pricing / Override Price Book to get prices directly from the price book based on the basket currency. Also sets basket attributes with faux information to help create an order in SFCC (Shipping Address, Billing Address, Customer Email Address, ESW Payment Method). Sets required product line item custom attributes (ESW Unit Price, ESW Delta Rounding Value). | | `dw.ocapi.shop.order.afterPOST` | `/int_eshopworld_headless/cartridge/scripts/ocapi/shop/hooks/orderHooks.js` | Sets order-level custom attributes: `eswFxrate`, `eswShopperCurrencyOrderDiscount`, `eswDeliveryOptions`. Also fetches and stores override shipping method rates used by ESW Checkout. To store override shipping methods JSON with rates, the ESW plugin uses `eswDeliveryOptions`, an order-level custom attribute available in the `systemobjects_headless.xml` metadata file. | | `dw.ocapi.shop.order.modifyPOSTResponse` | `/int_eshopworld_headless/cartridge/scripts/ocapi/shop/hooks/orderHooks.js` | Calls ESW Checkout service and appends the service response into the Order OCAPI `[POST] orderResponse` document. | ### 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. ```json { "product_items": [ { "product_id": "750518699721", "quantity": 1 }, { "product_id": "750518699769", "quantity": 1 } ], "shipments": [ { "shipping_method": { "id": "POST" } } ], "currency": "USD" } ``` ### 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**. ### 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 | ESW Parameters | Type | Description | Notes | | --------------- | ------------------ | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `price` | Decimal (Required) | Price of the product. | - | | `country` | String (Required) | Two-letter ISO code of the shopper's country. | - | | `currency` | String (Optional) | Three-letter ISO code of the shopper's local currency. | If provided, the ESW plugin uses this currency. If not provided, the ESW plugin uses the currency code provided in the **ESW Default Country Currency Mapping** site preference. | | `applyAdjust` | Boolean (Optional) | Indicates if the country adjustment should be applied. | If provided, the country adjustment value is applied to the price accordingly. | | `applyRounding` | Boolean (Optional) | Indicates if the prices should be rounded. | If provided, the prices are rounded accordingly. | #### Response The formatted converted price in the shopper currency. ### 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.esw.com/shopify/salesforce-commerce-cloud/cartridge-setup/headless-ocapi-architecture.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.